This directory contains SC documentation, powered by Sphinx.

To generate documentation as a webpage, run make html from this directory. The output will be generated in _build/html/index.html. You can either open up this file directly in a web browser, or serve the docs using python -m http.server -d _build/html. This will display the documentation at http://localhost:8000.

In order to generate docs, you will need to make sure you have Graphviz installed. On a Mac brew install graphviz, or on Linux sudo apt install graphviz.

If you have a Latex distribution installed, you can also generate PDF documentation through make latexpdf. For a full list of targets Sphinx supports, run make from this directory.

In order to generate the PDF docs, you will need to install the following additional packages:

  sudo apt install latexmk
  sudo apt install texlive-latex-extra
  sudo apt install imagemagick

The documentation entry point is index.rst. For now, this file just links to an api.rst page that includes the API documentation autogenerated from Python files. This follows the structure of other Python projects that use Sphinx for documentation, such as Flask.

conf.py contains basic Sphinx configuration, including the project name, documentation theme, and extensions. Makefile and make.bat provide build shortcuts, and are autogenerated by Sphinx itself.

This directory also contains an SC CLI reference and schema reference. These can be integrated into our Sphinx docs in the future.

Sphinx supports reStructuredText markup by default. Docs can be written in prose using this markup language, and Python API docs can also be autogenerated from docstrings.

In order to add autogenerated Python API docs for a given module, insert the following placeholder into an rst file:

.. automodule:: siliconcompiler.<mod_name>
    :members:

(see api.rst for examples).

We've configured Sphinx using the Napoleon extension to support Google-style Python docstrings. For more info on how to write these, see the relevant Google style guide section and the Napoleon documentation's examples.