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

The VTR documentation 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 lightweight mark-up language for text documents.

Currently VTR's documentation 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 to to install Doxygen (Optional) and the python dependencies. You can use your distribution's package manager to install Doxygen. Ubuntu and Debian users can use the following command:

    $ sudo apt install doxygen

While Fedora and RHEL users can use the following command:

    $ sudo dnf install doxygen

You can install python dependencies by fist optionally making a virtual environment:

    $ python -m venv .venv
    $ source .venv/bin/activate

And then using the requirements file to install the dependencies:

    $ 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 documentation with the web-browser of your choice.
For instance:

    $ firefox _build/html/index.html


If you want to skip automatic Doxygen XML generation, you can set:

    $ export SKIP_DOXYGEN=True

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 their 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

