vicampo/docs-generator repository overview

The docs-generator image wraps sphinx to be able to run it everywhere (in docker). As of now this image is based on the official python3-6-stretch image which (yes!) is very large. This could be optimized of course.

⁠Usage

You have a service and want to document it? Great! Go fetch the image:

docker pull  vicampo/docs-generator:latest

Using this image requires running its docs.sh script like this

docker run --rm  vicampo/docs-generator:latest  /src/docs.sh  CMD

Where CMD is one of init or build.

Initialize your service with init

In order to generate documentation you need to configure sphinx. If you know sphinx and how to generate a configuration for that, you can do that manually. But its actually very simple to get going:

docker run --rm -v $PWD:/service-root vicampo/docs-generator:latest  /src/docs.sh init

The above command creates a docs/ folder in you service and copies needed files into it. That is mainly the configuration for Sphinx, and the theme used. http://www.sphinx-doc.org/en/stable/config.html⁠ You definitely want to checkout conf.py and adjust some of its settings. It already is a trimed down version of the quickstart build. Most settings are very self explanatory.

After the docs/conf.py changes, add the build folder from sphinx to the gitignore.

`docs/_build/*`

Build your documentation with build

Although you have not written anything useful yet, you can try to build your docs now.

docker run --rm  -v $PWD:/service-root  vicampo/docs-generator:latest  /src/docs.sh  build

This should generate you a bunch of HTML Files unter docs/_build/ of which you can just open index.html in a browser.

Now go and write some great documentation. Have a look at docs/introduction.rst! or this repository's docs to get you started.

You can build the image

make build

You can enter the image

make shell

Currently /src/docs.sh is the main tool used in this image. While being a simple starting point it has its drawbacks.

⁠References

• https://hub.docker.com/r/vicampo/docs-generator/⁠
• https://github.com/bukalapak/snowboard⁠

Draw graphs using Mermaid: https://github.com/mgaitan/sphinxcontrib-mermaid⁠ https://mermaidjs.github.io/⁠