This page is a short introduction to our documentation file structure and our documentation workflow. This is mainly important for those who want to contribute to our Documentation.
Setting up Sphinx¶
To get a Sphinx setup up and running, you can either install it directly on your system or you simply use our docker container which comes ready to use for our docs.
Sphinx Docker Image¶
docker run -t -i --rm -p 8080:8000 -v <pathToTheDocsDir>:/opt/docs webdevops/sphinx sphinx-autobuild -H 0.0.0.0 /opt/docs html
- To simply use it just change the <pathToTheDocsDir> with the path to the projects docs directory.
- For example you cloned the **php-docker-boilerplate* repository to
/home/myuser/projects/php-docker-boilerplate, the directory to the docs directory would be
[I 160328 16:39:17 server:281] Serving on http://0.0.0.0:8000 [I 160328 16:39:17 handlers:59] Start watching changes [I 160328 16:39:17 handlers:61] Start detecting changes
- This command calls docker run which simply will run a container.
- The parameters -t and -i are standard to run pseudo TTY and interactive mode.
- The parameter –rm will remove older containers if they exist.
- With -p 8080:8000 we tell docker to expose the port 8000 inside the container to the local port 8080 (you can change that port if you like).
- The parameter -v <pathToTheDocsDir>:/opt/docs sets the mounting of our documentation directory inside the container. While <pathToTheDocsDir> is our documentation directory, we mount it to /opt/docs inside the container.
- Now we tell docker, which image to take, in this case webdevops/sphinx. After that we add the command we want to execute inside the container.
/opt/docsto a folder
htmlis then rendered to a webserver that listens to the host (the -H option) 0.0.0.0 which allows us to call it with whatever domain from the host system.
Sphinx Manual Setup¶
python-pipin the Package manager of your operating system.
pip install sphinx sphinx-autobuild recommonmark
sphinx-autobuildfeature to generate the html code.
# example assuming you cloned the project php-docker-boilerplate to /home/myuser/projects/php-docker-boilerplate cd /home/myuser/projects/php-docker-boilerplate/documentation/docs sphinx-autobuild . ~/projects/php-docker-boilerplate-docs
To prevent chaos within our documents and to ensure Read the Docs is able to render our documents as expexted, we sustain some standards across our documentation files.
Our file structure consists of the following rules:
- Our documentation files for Read the Docs always reside in the project directory under the subdirectory
docsdirectory has to contain at least the following files: conf.py, index.rst, make.bat, Makefile
- The file index.rst inside the documentation root must contain one or multiple
toctreedirectives that contain a backlink to this documentation and a link to every menu documentation page, listed in the main menu.
- Every documentation file must be inside a subdirectory
- In case a documentation page consists of multiple pages, another subdirectory is added with the name of that section. Each section has one entry point, named index.rst which also contains a
toctreedirective referencing ech subpage.
- Any resources are contained in a subdirectory
docs/resources. Each type of resource is placed inside another directory like
.. toctree:: Back to Project Overview <http://webdevops-documentation.readthedocs.org/en/latest/> content/introduction .. toctree:: :caption: Documentation content/gettingStarted/index content/usage/index content/components/index content/contribute/index
toctreedirective has an intendation.
toctreedefinition and the listed items.
:caption:declaration, allows us to define a headline for a set of toctree items.
toctreefor for this subpage to reference them.
.. toctree:: :maxdepth: 1 code documentation
:maxdepth:directive in subpages.
Toctree Directive for Structure¶
toctree, it should not be the tool of choice when it comes to defining a hierarchical structure.
toctreeto split bigger parts of the documentation into smaller chunks.
Headlines and Hierarchy¶
=========== My Headline ===========
- # with overline, for parts
- * with overline, for chapters
- =, for sections
- -, for subsections
- ^, for subsubsections
- ”, for paragraphs