doc/README

Overview
--------------------------

The VTR documentaion is generated using sphinx, a python based documentation generator.

The documentation itself is written in re-structured text (files ending in .rst), which
is a lightwieght mark-up language for text documents.

Currently VTR's documenation is automatically built by https://readthedocs.org/projects/vtr/ and is served at:

    https://docs.verilogtorouting.org/


How to build documentation
--------------------------

To build the documentation locally you need sphinx installed:

    For ubuntu/debian based systems:

        $ apt-get install python-sphinx

    To properly build citations and the bibliography, we use the sphinxcontrib-bibtex extension:

        $ pip install sphinxcontrib-bibtex

    To install all the python requirements:

        $ pip install -r requirements.txt

To build the documentation just run:

    $ make html

from the main documentation directory (i.e. <vtr_root>/doc).

This will produce the output html in the _build directory.

You can then view the resulting documention with the web-browser of your choice.
For instance:

    $ firefox _build/html/index.html


Documentation Layout
--------------------

The root of the VTR documentation is the 'src/index.rst' file.

This file references other files using the toctree directive.

Key sub-systems of VTR have their documentation located in a sub-directory (e.g. vpr, arch), with thier own index.rst.

Within each sub-directory there are usually several other .rst files which containing actual documentation for the subsystem.
Each of these files must be referred to in the sub-system's index.rst in order to be included in the generated documentation.


Useful Resources:
-----------------

Re-Structured Text syntax: 
    http://www.sphinx-doc.org/en/stable/rest.html

Paragraph-level markup: 
    http://www.sphinx-doc.org/en/stable/markup/para.html

Inline markup:
    http://www.sphinx-doc.org/en/stable/markup/inline.html