bootstrap-vz/docs/README.rst

:orphan:


Documentation
=============
Both the end-user and developer documentation is combined into a single sphinx
build (the two were previously split between github pages and sphinx).


Building
--------
To build the documentation, simply run ``tox -e docs`` in the project root.
Serving the docs through http can be achieved by subsequently running
``(cd docs/_build/html; python -m SimpleHTTPServer 8080)`` and accessing them
on ``http://localhost:8080/``.


READMEs
-------
Many of the folders in the project have a README.rst which describes
the purpose of the contents in that folder.
These files are automatically included when building the documentation,
through use of the `include`__ directive.

__ http://docutils.sourceforge.net/docs/ref/rst/directives.html#including-an-external-document-fragment

Include files for the providers and plugins are autogenerated
through the sphinx conf.py script.


Links
-----
All links in rst files outside of ``docs/`` (but also ``docs/README.rst``) that
link to other rst files are relative and reference folder names when the link
would point at a README.rst otherwise. This is done to take advantage of the
github feature where README files are displayed when viewing its parent folder.
When accessing the ``manifests/`` folder for example, the documentation for how
manifests work is displayed at the bottom.

When sphinx generates the documentation, these relative links are
automatically converted into relative links that work inside the generated
html pages instead.
If you are interested in how this works, take a look at the
link transformation module in ``docs/transform_github_links``.