SC Documentation

This directory contains SC documentation, powered by Sphinx.

Generating docs

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.

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.

Docs structure

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.

Writing docs

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.