.. _documentation:

Documentation (information for maintainers of the NBT package)
==============================================================

The documentation of the NBT library is available on the wiki
(https://github.com/twoolie/NBT/wiki), and is automatically generated from the
source code in combination with auxiliary files in the doc directory.

Requirements
------------

Install requirements::

    pip install sphinx
    pip install sphinxcontrib-restbuilder

Check out the wiki repository and make a symlink to it::

    git clone https://github.com/twoolie/NBT.wiki.git
    cd path_to/NBT/doc
    ln -s path_to/NBT.wiki

Generate the documentation
--------------------------

Generate the documentation::

    cd path_to/NBT/doc
    make wiki

Alternatively, execute the following command

::

    sphinx-build -b rst -d path_to/NBT/doc/build/doctrees -c path_to/NBT/doc \
            -a path_to/NBT/doc path_to/NBT/doc/NBT.wiki

Upload the documentation

Verify the documentation and upload the changes::

    cd path_to/NBT.wiki
    git status
    git add *
    git commit -m "Update documentation"
    git push

Sphinx Build System
-------------------

The following files are used by the documentation build system:

``Makefile``
    Build script. Run as "make wiki". Calls sphinx-build.
``conf.py``
    Sphinx configuration file. Defines settings specific for this build system.
``python.inv``
    Intersphinx mapping from classes in the standard library to a documentation 
    URL. This is only an excerpt from http://docs.python.org/3.2/objects.inv,
    and in version 1 of the Sphinx inventory format.

The following directories are used by the documentation build system. Both are 
ignored by git.

``build``
    Build folder where cache files and output of Sphinx is stored.
``NBT.wiki``
    Symbolic link to a checkout of the NBT.wiki git repository.

Known Bugs
----------

The genindex, modindex and search page are only generated for HTML, not for the wiki.

