Add documentation about the documentation

CONTRIBUTING.rst

@@ -1,24 +1,24 @@
 Contributing
 ============
 
+
 Sending pull requests
 ---------------------
-
 Do you want to contribute to the bootstrap-vz project? Nice! Here is the basic workflow:
 
-+ Read the `development guidelines <#development-guidelines>`__
+* Read the `development guidelines <#development-guidelines>`__
-+ Fork this repository.
+* Fork this repository.
-+ Make any changes you want/need.
+* Make any changes you want/need.
-+ Check the coding style of your changes using `tox <http://tox.readthedocs.org/>`__ by running `tox -e flake8`
+* Check the coding style of your changes using `tox <http://tox.readthedocs.org/>`__ by running `tox -e flake8`
   and fix any warnings that may appear.
   This check will be repeated by `Travis CI <https://travis-ci.org/andsens/bootstrap-vz>`__
   once you send a pull request, so it's better if you check this beforehand.
-+ If the change is significant (e.g. a new plugin, manifest setting or security fix)
+* If the change is significant (e.g. a new plugin, manifest setting or security fix)
   add your name and contribution to the `changelog <CHANGELOG.rst>`__.
-+ Commit your changes.
+* Commit your changes.
-+ Squash the commits if needed. For instance, it is fine if you have multiple commits describing atomic units
+* Squash the commits if needed. For instance, it is fine if you have multiple commits describing atomic units
   of work, but there's no reason to have many little commits just because of corrected typos.
-+ Push to your fork, preferably on a topic branch.
+* Push to your fork, preferably on a topic branch.
 
 From here on there are two paths to consider:
 
@@ -31,8 +31,6 @@ If it is a bug/security fix:
 
 * Send a pull request to the `master` branch.
 
---
-
 Please try to be very descriptive about your changes when you write a pull request, stating what it does, why
 it is needed, which use cases this change covers etc.
 You may be asked to rebase your work on the current branch state, so it can be merged cleanly.
@@ -54,7 +52,7 @@ these guidelines are not rules , they are advice on how to better add
 value to the bootstrap-vz codebase.
 
 
-+ **The manifest should always fully describe the resulting image. The
+* **The manifest should always fully describe the resulting image. The
   outcome of a bootstrapping process should never depend on settings
   specified elsewhere.**
 
@@ -65,7 +63,7 @@ value to the bootstrap-vz codebase.
   for example can be reproduced using the manifests available
   in the manifest directory of bootstrap-vz.
 
-+ **The bootstrapper should always be able to run fully unattended.**
+* **The bootstrapper should always be able to run fully unattended.**
   
   For end users, this guideline minimizes the risk of errors. Any
   required input would also be in direct conflict with the previous
@@ -76,7 +74,7 @@ value to the bootstrap-vz codebase.
   process multiple times though, any prompts in the middle of that
   process may significantly slow down the development speed.
 
-+ **The bootstrapper should only need as much setup as the manifest
+* **The bootstrapper should only need as much setup as the manifest
   requires.**
 
   Having to shuffle specific paths on the host into place
@@ -88,7 +86,7 @@ value to the bootstrap-vz codebase.
   the VirtualBox Guest Additions ISO or tools like ``parted`` that
   need to be installed on the host.
 
-+ **Roll complexity into which tasks are added to the tasklist.**
+* **Roll complexity into which tasks are added to the tasklist.**
 
   If a ``run()`` function checks whether it should do any work or simply be
   skipped, consider doing that check in ``resolve_tasks()`` instead and
@@ -99,7 +97,7 @@ value to the bootstrap-vz codebase.
   conclude that the file has either been overwritten or that the
   search & replace does not work correctly.
 
-+ **Control flow should be directed from the task graph.**
+* **Control flow should be directed from the task graph.**
 
   Avoid creating complicated ``run()`` functions. If necessary, split up
   a function into two semantically separate tasks.
@@ -111,28 +109,28 @@ value to the bootstrap-vz codebase.
   can replace the volume creation task with a task of its own that
   creates a volume from a snapshot instead, but still reuse the mount task).
 
-+ **Task classes should be treated as decorated run() functions, they 
+* **Task classes should be treated as decorated run() functions, they 
   should not have any state**
 
   Thats what the BootstrapInformation object is for.
 
-+ **Only add stuff to the BootstrapInformation object when really necessary.**
+* **Only add stuff to the BootstrapInformation object when really necessary.**
 
   This is mainly to avoid clutter.
 
-+ **Use a json-schema to check for allowed settings**
+* **Use a json-schema to check for allowed settings**
   The json-schema may be verbose but it keeps the bulk of check work outside the
   python code, which is a big plus when it comes to readability. This of
   course only applies bas long as the checks are simple. You can of
   course fall back to doing the check in python when that solution is
   considerably less complex.
 
-+ **When invoking external programs, use long options whenever possible**
+* **When invoking external programs, use long options whenever possible**
 
   This makes the commands a lot easier to understand, since
   the option names usually hint at what they do.
 
-+ **When invoking external programs, don't use full paths, rely on ``$PATH``**
+* **When invoking external programs, don't use full paths, rely on ``$PATH``**
 
   This increases robustness when executable locations change.
   Example: Use ``log_call(['wget', ...])`` instead of ``log_call(['/usr/bin/wget', ...])``.
@@ -143,16 +141,26 @@ Coding style
 bootstrap-vz is coded to comply closely with the PEP8 style
 guidelines. There however a few exceptions:
 
-+ Max line length is 110 chars, not 80.
+* Max line length is 110 chars, not 80.
-+ Multiple assignments may be aligned with spaces so that the = match
+* Multiple assignments may be aligned with spaces so that the = match
   vertically.
-+ Ignore ``E101``: Indent with tabs and align with spaces
+* Ignore ``E101``: Indent with tabs and align with spaces
-+ Ignore ``E221 & E241``: Alignment of assignments
+* Ignore ``E221 & E241``: Alignment of assignments
-+ Ignore ``E501``: The max line length is not 80 characters
+* Ignore ``E501``: The max line length is not 80 characters
-+ Ignore ``W191``: Indent with tabs not spaces
+* Ignore ``W191``: Indent with tabs not spaces
 
 The codebase can be checked for any violations quite easily, since those rules are already specified in the
 `tox <http://tox.readthedocs.org/>`__ configuration file.
 ::
 
     tox -e flake8
+
+
+Documentation
+-------------
+When developing a provider or plugin, make sure to update/create the README.rst
+located in provider/plugin folder.
+Any links to other rst files should be relative and work, when viewed on github.
+For information on `how to build the documentation <docs#building>`_ and how
+the various parts fit together,
+refer to `the documentation about the documentation <docs>`__ :-)

README.rst

@@ -24,7 +24,7 @@ There, you can discover `what the dependencies <#dependencies>`__ for
 a specific cloud provider are, `see a list of available plugins <bootstrapvz/plugins>`__
 and learn `how you create a manifest <manifests>`__.
 
-Note to developers: `The documenation <docs>`__ is generated in a rather peculiar and nifty way.
+Note to developers: `The documentaion <docs>`__ is generated in a rather peculiar and nifty way.
 
 Installation
 ------------

docs/README.rst

@@ -1,5 +1,44 @@
 :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``.