Add documentation web site

[eine]

Since the readme contains so much useful info, it is starting to get annoying to scroll top/down in order to search/compare the desired content. I suggest to use an static site generator (such as Hugo, Jekyll or Sphinx) to create a website and upload/deploy it to branch gh-pages (for it to be served at adumont.github.io/hrm-cpu).

I think that Hugo is the best option, because it expects sources to be written in Markdown (which is already the case) and because it is a single static binary. However, Hugo produces HTML sites only.

Conversely, Sphinx allows to use the same sources to generate both a web site and a PDF report. See, for example, ghdl.rtfd.io and https://ghdl.readthedocs.io/_/downloads/en/latest/pdf/. Although Markdown sources can be used, Sphinx is primarily meant for reStructuredText sources. See gohugoio/hugo#6332 (comment).

Moreover, it is straightforward to have a GitHub Actions automatically build and update the site after each commit is pushed. For example:

• Using Hugo: https://github.com/eine/issue-runner/blob/master/.github/workflows/doc.yml (https://eine.github.io/issue-runner)
• Using Sphinx: https://github.com/VUnit/vunit/blob/master/.github/workflows/docs.yml (vunit.github.io)

Although I cannot decide which tool or theme to use for you, I'd be glad to help you set up the CI job.

[adumont]

Thanks @eine , it's interesting feedback. I'll have to take that into consideration and investigate those options you mention.

[eine]

Great! Please, do not hesitate to ask about initial configuration/setup of any of the tools. Since it is mostly a one-time task, I'd rather you focus on more relevant tasks, such as actually thinking about the best organisation/hierarchy of the site.