Generate an static site and host it in GitHub Pages

[umarcor]

This repository does not have a documentation or web site yet. However, there are several features which might be better comunicated by doing so.

• GHDL, Yosys and netlistsvg allow generating diagrams of the components or the whole design. Each of them provides a different level of abstraction or a different style.
• VUnit can produce XUnit reports which can be processed with e.g. lukejpreston.github.io/xunit-viewer. See umarcor.github.io/osvb/apis/logging.
• In ghdl/extended-tests, Microwatt is one of the projects used for testing ghdl-dom. pytest is used and the result is processed with pytest-reporter to produce ghdl.github.io/extended-tests.
  • pyVHDLModel has two main planned use cases:
    • A linter/formatter.
    • Entity/package/architecture documentation generator. Similar to TerosHDL's documenter demo and/or symbolator, but using GHDL as the backend/parser instead of an "external" parser.
  • pyVHDLModel is work in progress, but as seen in ghdl.github.io/extended-tests, 98% of the analysed sources can be processed already. Find a practical usage of pyVHDLModel in Open Source VHDL Design Explorer (OSVDE).

Two different static site documentation generation systems are used in the open source hardware community mostly:

• Sphinx is probably the most used (GHDL, VUnit, SymbiFlow, FuseSoc, cocotb, Fomu workshop, OSVB, pyVHDLModel, TerosHDL, Wishbone....). As a result, there are some very interesting benefits:

  • intersphinx allows cross-referencing between sites similarly to internal references. That allows keeping the ecosystem in sync, even when the content is moved/reworked.
  • SymbiFlow/sphinxcontrib-hdl-diagrams is an extension for generating diagrams with Yosys/netlistsvg "automagically". Supporting VHDL/GHDL is work in progress: vhdl support and configuration page SymbiFlow/sphinxcontrib-hdl-diagrams#72, Support using sphinxcontrib-hdl-diagrams on MSYS2 SymbiFlow/sphinxcontrib-hdl-diagrams#73.
  • bavovanachte/sphinx-wavedrom is an extension for generating waveforms with wavedrom. See, for instance, wishbone-interconnect.org/specs/b3/03_classic.
  • One of the goals of pyVHDLModel is to generate a VHDL domain for Sphinx (placeholder: VHDL/sphinx-vhdl).

• asciidoctor is probably the second most used (NEORV32, hdl/{containers,constraints,MINGW-packages}, Greg, RaspberryPi...).

  • asciidoctor-diagram supports wavedrom and bytefields, similarly to the sphinx-wavedrom extension.
  • Unfortunately, there is no solution in asciidoc or asciidoctor equivalent to intersphinx. In fact, asciidoctor generates single page HTML documents. In order to generate "sites", maintainers recommend using Antora (another tool written in JavaScript that wraps asciidoctor -Ruby-). As Luke@RaspberryPi commented, it is not strange to use some Python as well.

A few years ago, the Linux kernel evaluated both. See https://lwn.net/Articles/692704/.

Summarising, I like the asciidoctor syntax (I find it much easier to write than rst). I find the documentation of NEORV32 to be awesome. However, Sphinx's site generation and cross-referencing features are very valuable. Hence, I would probably recommend to go with Sphinx.

I could help with setting up CI for having the docs automatically built and pushed to gh-pages (thus, served at antonblanchard.github.io/microwatt).