mirror of
https://github.com/bigchaindb/bigchaindb.git
synced 2024-10-13 13:34:05 +00:00
1086c3a5c4
According to https://www.ietf.org/rfc/rfc2616.txt a 201 Created status code MUST only be returned when: "The origin server MUST create the resource before returning the 201 status code." hence, a 202 Accepted's definition is more appropriate: "The request has been accepted for processing, but the processing has not been completed. The entity returned with this response SHOULD include an indication of the request's current status and either a pointer to a status monitor or some estimate of when the user can expect the request to be fulfilled."
The BigchainDB Documentation Strategy
- Include explanatory comments and docstrings in your code. Write Google style docstrings with a maximum line width of 119 characters.
- For quick overview and help documents, feel free to create
README.mdor otherX.mdfiles, written using GitHub-flavored Markdown. Markdown files render nicely on GitHub. We might auto-convert some .md files into a format that can be included in the long-form documentation. - We use Sphinx to generate the long-form documentation in various formats (e.g. HTML, PDF).
- We also use Sphinx to generate Python code documentation (from docstrings and possibly other sources).
- We also use Sphinx to document all REST APIs, with the help of the
httpdomainextension.
How to Generate the HTML Version of the Long-Form Documentation
If you want to generate the HTML version of the long-form documentation on your local machine, you need to have Sphinx and some Sphinx-contrib packages installed. To do that, go to a subdirectory of docs (e.g. docs/server) and do:
pip install -r requirements.txt
You can then generate the HTML documentation in that subdirectory by doing:
make html
It should tell you where the generated documentation (HTML files) can be found. You can view it in your web browser.