Open V0XNIHILI opened 3 months ago
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.
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.
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
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