1
0
mirror of https://github.com/bigchaindb/bigchaindb.git synced 2024-06-16 17:43:21 +02:00
bigchaindb/docs/README.md
lana-shanghai 4a008e51e3
[WIP] Documentation re-org (#2694)
* Reorganized docs

* Fixed internal links in basic usage

* fixed the docker-compose command and volume for docs

* fixed docs tests

* fix travis docs test

* tox ini file

* fixed readme localhost links

* edited tox and test docs to previous state

* Fix tests errors related to docs reorganization

Signed-off-by: David Dashyan <mail@davie.li>

* Added ansible script installation option

Signed-off-by: Lana Ivina <lana@ipdb.io>

* Added ansible script to network setup guide

Signed-off-by: Lana Ivina <lana@ipdb.io>

* Hid the non-working button for now. 

Signed-off: Lana Ivina <lana@ipdb.io>

* Try now button

Co-authored-by: David Dashyan <mail@davie.li>
2020-05-18 20:22:26 +07:00

2.4 KiB

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.md or other X.md files, 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 httpdomain extension.

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

If you're building the Server docs (in docs/server) then you must also do:

pip install -e ../../

Note: Don't put -e ../../ in the requirements.txt file. That will work locally but not on ReadTheDocs.

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.

Building Docs with Docker Compose

You can also use Docker Compose to build and host docs.

$ docker-compose up -d bdocs

The docs will be hosted on port 33333, and can be accessed over localhost, 127.0.0.1 OR http:/HOST_IP:33333.