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