mirror of
https://github.com/bigchaindb/bigchaindb.git
synced 2024-10-13 13:34:05 +00:00
9be68c972d
- Standardize docker-compose workflow
- Change docker-compose version to 2.1
- why one might ask? because compose version
3.0 does not support depends on and inherits
like we want to and is more aimed towards migration to using
`docker stack`, for our current strategy `2.1` is a better choice.
- change `bdb` service `bigchaindb` service
- why? Introduced a new proxy service `bdb` which is just a dummy
`busybox` image.
- why? because this ensure via healthcheck of bigchaindb that BigchainDB
has started properly and makes a `curl` to ensure HTTP API server is up
and running.
- why? Because we have had scenarios where BigchainDB is not started
via docker compose and user has to check out the logs to find out what
the problem might be. This ensure that bigchaindb is up and running.
- Does this change deployment workflow? No.
- The only thing change is that if you want to run commands inside a bigchaindb
container e.g. `pytest` now you have to run the following command:
`docker-compose run --rm --no-deps bigchaindb pytest -v --cov=bigchaindb`
as opposed to `docker-compose run --rm --no-deps bdb pytest -v --cov=bigchaindb`
- Remove env variable `BIGCHAINDB_START_TENDERMINT`
- Remove TENDERMINT_INTEGRATION.rst and move to the new docs
- Change mdb -> mongodb because the other services were named with
full name.
- Add example to run specific tests or from a file
- Update config.toml for tendermint to use `bigchaindb` as proxy app
instead of `bdb`
- Remove `network` directory because it is deprecated
- Add comment about why PYTHONBUFFERED is used
45 lines
2.2 KiB
Markdown
45 lines
2.2 KiB
Markdown
- [Documentation on ReadTheDocs](http://bigchaindb.readthedocs.org/)
|
|
- [BigchainDB Upgrade Guides](upgrade-guides/)
|
|
|
|
# The BigchainDB Documentation Strategy
|
|
|
|
* Include explanatory comments and docstrings in your code. Write [Google style docstrings](https://google.github.io/styleguide/pyguide.html?showone=Comments#Comments) 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](https://help.github.com/categories/writing-on-github/). 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](http://www.sphinx-doc.org/en/stable/) to generate the long-form documentation in various formats (e.g. HTML, PDF).
|
|
* We also use [Sphinx](http://www.sphinx-doc.org/en/stable/) 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](https://pythonhosted.org/sphinxcontrib-httpdomain/).
|
|
|
|
# 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:
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
If you're building the *Server* docs (in `docs/server`) then you must also do:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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](https://docs.docker.com/compose/) to build and host docs.
|
|
|
|
```text
|
|
$ docker-compose up -d bdocs
|
|
```
|
|
|
|
The docs will be hosted on port **33333**, and can be accessed over [localhost](http:/localhost:33333), [127.0.0.1](http:/127.0.0.1:33333)
|
|
OR http:/HOST_IP:33333.
|
|
|
|
|