http-apis / documentation-hydrus

Sphinx documentation, for deploying in readthedocs.org

documentation-hydrus

This reposity contains documentation of hydrus built using Sphinx

You can check the current documentation here

Steps to build doc

• Clone this repository.

$ git clone https://github.com/HTTP-APIs/documentation-hydrus.git

• Clone the hydrus repository.

$ git clone https://github.com/HTTP-APIs/hydrus.git

• It is recommended to use virtualenv and virtualenvwrapper to maintain a clean environment.

$ source `which virtualenvwrapper.sh`
$ mkvirtualenv -p python3 hydrus
(hydrus) $ deactivate         # To deactivate the virtual environment
$ workon hydrus               # To activate virtual environment

• Install requirements

(hydrus)$ cd documentation-hydrus 
(hydrus)$ pip install -r requirements.txt

• Install hydrus

(hydrus)$ cd hydrus           # Go to your hydrus folder
(hydrus)$ pip install -e .    # To install hydrus

• Copy the doc folder from documentation-hydrus folder to hydrus folder (Important step).

• Everything is done now you can build the doc's .

(hydrus)$ cd hydrus/doc                 # The doc folder which was copied from documentation-hydrus to hydrus
(hydrus)$ sphinx-build -b html path/to/hydrus/doc/rst path/to/hydrus/doc/_build/html

Where "path/to/hydrus/doc/rst" and "path/to/hydrus/doc/_build/html" are your local folder path.

• To make a clean build

(hydrus)$ make clean
(hydrus)$ sphinx-build -b html path/to/hydrus/doc/rst path/to/hydrus/doc/_build/html

documentation-hydrus's Issues

module not found error

I am trying to build the documentation. This is the error that I am getting.

I have installed hydrus by cd into hydrus folder and then pip install -e .

Design document on the hydrus workflow

As hydrus define a precise workflow like:

1. the API designer write a SWAGGER/OpenAPI JSON document that describes his/her API (yet to be implemented, hopefully this year. Please consider submitting an application for this)
2. hydrus parser will parse this JSON into a HYDRA API documentation (example here)
3. hydrus deploys the Web server byt parsing the outcome at 2.
4. hydrus serves the API
5. HYDRA-aware generic clients can use the API

We need an extensive document that improve the current WIKI by adding a detailed description of this workflow, with references to RDF codebase and Hydra draft.

References:

• URSA

Create autodoc building and deploying for hydrus

Get into the code and write a report about URSA

URSA is a very interesting C# library that implements HYDRA:

• code
• documentation

Having somebody that can get into the repository and documentation and write a brief report about the interesting features we can use in hydrus would be really helpful.

Research possibility of parsing from JSON schema

The JSON schema draft seems to be takjng momentum.

I think this is pretty relevant to what we are doing: http://json-schema.org
There is also a wide array of tools like: https://github.com/aromanovich/jsl
Python DSL for describing JSON schemas http://jsl.readthedocs.org/
For hyperschemas https://github.com/core-api/python-jsonhyperschema-codec

Investigate possible synergies.

Improve README

README.md should provide information about how the repo has been developed and which design choices have been made.

Move documentation to hydrus

Instead of having separate repos for each project, we should add all documentation in the doc/ path into the hydrus repo. This way we build documentation directly with hydrus.

We should also implement the same things for other repos that need documentation.

Update documentation to latest merge on master

Sphinx documentation has to be rebuild and republished

Publish the Wiki repository content alongside with hydrus documentation

Provide a hook to parse and publish the content in https://github.com/HTTP-APIs/hydra-ecosystem-wiki alongside with hydrus API in readthedocs.

Update documentation with respect to the changes done in hydrus