Documentation setup thoughts

[V0XNIHILI]

Right now, all the documentation is hardcoded into HTML files and Jupyter notebooks that are inside this repository and are then hosted on https://xilinx.github.io/brevitas/.

For quality + ease of maintenance, would it maybe be an idea to use a tool like Docusaurus, ReadTheDocs or keep Sphinx but store the content in Markdown/RST files instead of rich HTML? This would be able to make the documentation easier to edit and maintain.

See for example how this is done in PyTorch: https://github.com/pytorch/pytorch/blob/main/docs/source/autograd.rst

[Giuseppe5]

I believe we have a similar setup, with the HTML files in the doc folder being automatically generated starting from the .rst files in the docsrc folder.

[V0XNIHILI]

Ah right, I didnt see that, thanks! Maybe it would be better not to commit the HTML files though, because now both the source and the generated files are commited: so every time one file changes, another one changes too and it contains the same information. For example, whenever I was searching through the code base for some things, I found references in many HTML files, but those files are hard to read in a text editor.

[Giuseppe5]

We need to commit them because they are automatically picked up by GitHub to generate the documentation website.

I know that there are alternatives to this approach and maybe we'll switch in the future but I wouldn't say it's a priority at the moment