Use Sphinx to create awesome documentation for the project

[mithro]

Sphinx is the best tool for documenting Python projects. This project should have awesome documentation.

You can probably steal a lot of inspiration from projects like;

• https://github.com/SymbiFlow/symbiflow-examples // http://symbiflow-examples.rtfd.io/
• https://github.com/im-tomu/fomu-workshop // https://fomu-workshop.rtfd.io/
• https://github.com/google/skywater-pdk // https://skywater-pdk.readthedocs.io/
• https://github.com/olofk/edalize // https://edalize.readthedocs.io/en/latest/
• https://github.com/SymbiFlow/python-symbiflow-v2x // https://python-symbiflow-v2x.readthedocs.io/en/latest/
• https://docs.verilogtorouting.org/en/latest/
• OpenLane / OpenROAD documentation
• Any decent Python module

You might find the following plugins interesting;

• https://sphinxcontrib-hdl-diagrams.rtfd.io/
• https://github.com/bavovanachte/sphinx-wavedrom
• https://github.com/SymbiFlow/sphinx-verilog-domain
• https://github.com/Paebbels/sphinxcontrib-vhdldomain

[mithro]

@umarcor might also be able to provide some tips and pointers.

[umarcor]

We use BuildTheDocs in many projects. It's a Python script (https://github.com/buildthedocs/btd/blob/master/btd/__init__.py) available as a GitHub Action (https://github.com/buildthedocs/btd/blob/master/action.yml), which can be used in a workflow as follows:

      - name: '📓 BuildTheDocs (BTD)'
        uses: buildthedocs/btd@v0
        with:
          token: ${{ github.token }}
          skip-deploy: github.event_name == 'pull_request'

It builds the docs and pushes them to GitHub Pages (branch gh-pages).

For reference, see the .btd.yml, doc/conf.py and doc/Makefile files in any of the repos from github.com/edaa-org.