mirror of
https://github.com/bigchaindb/bigchaindb.git
synced 2024-10-13 13:34:05 +00:00
2386ca9d71
* Problem: core.py contains an unused class, `Bigchain` Solution: Remove core.py. Refactor BigchainDB Class to remove inheritance from Bigchain. * Problem: core.py contains an unused class, `Bigchain` Solution: Remove core.py. Refactor BigchainDB Class to remove inheritance from Bigchain. * Fixed flake8 complaint about too many blank lines * Attempting to fix Sphinx docs. This may result in some redundant commits, as I don't know what I'm doing, and I can't experiment without running the CI... Sorry in advance! * Attempting to fix Sphinx docs. This may result in some redundant commits, as I don't know what I'm doing, and I can't experiment without running the CI... Sorry in advance! * Updating from master changed BigchainDB.process_post_response to a private method, so I had to align with that. * Fixed a couple stale references to bigchaindb.Bigchain in docstrings * Missed a reference to `Bigchain` in a patch call... * Problem: BigchainDB class should be part of project root Solution: Removed the /tendermint directory and moved its contents to project root * Problem: Flake8 complained that imports were not at the top of the file Solution: Had to play around with the order of imports to avoid cyclic dependencies, but its working and style compliant now * Problem: Stale reference to /tendermint directory in the index Solution: Removed the references to /tendermint * Problem: Flake8 complaining of unused import in __init__.py Solution: The import is there so I can import App directly from bigchaindb, rather than from bigchaindb.core (which I think improves code readability. I added a # noqa to silence Flake8. * Problem: Stale references to `bigchaindb.tendermint.BigchainDB` in the rst files cause Sphinx to fail Solution: Updated the autodoc files to use `bigchaindb.BigchainDB` instead * Problem: Stale reference to the `tendermint` directory in an @patch in a disabled test Solution: Updated the @patch for completeness * Problem: BigchainDB class should be part of project root Solution: Removed the /tendermint directory and moved its contents to project root * Problem: Flake8 complained that imports were not at the top of the file Solution: Had to play around with the order of imports to avoid cyclic dependencies, but its working and style compliant now * Problem: Stale reference to /tendermint directory in the index Solution: Removed the references to /tendermint * Problem: Flake8 complaining of unused import in __init__.py Solution: The import is there so I can import App directly from bigchaindb, rather than from bigchaindb.core (which I think improves code readability. I added a # noqa to silence Flake8. * Problem: Stale references to `bigchaindb.tendermint.BigchainDB` in the rst files cause Sphinx to fail Solution: Updated the autodoc files to use `bigchaindb.BigchainDB` instead * Problem: Stale reference to the `tendermint` directory in an @patch in a disabled test Solution: Updated the @patch for completeness
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
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.