twizmwazin
commented
2 years ago ~So here's a plan that I think would work well, in two steps:~
~First step, start generating the docs with pdoc. This tool will generate our documentation from the docstrings in each repo, so there is no need to do anything manual like what we are currently doing, and no extra code or config needs to be added to repos themselves. pdoc also has some really neat features like a live server for editing docs, and it can export to md/html. This requires a change in the release pipeline, and possibly a few non-functional tweaks to module source. I'll plan to add a CI check because pdoc will attempt to import everything even when it wouldn't be imported by default, and we have some hidden modules that aren't directly importable and will need to be fixed.~
~Second step, we've raised the idea of versioning our docs before. The default templates do not allow us to do that currently, but I think it would be very easy to modify the templates to have a header bar where we can add some branding, a version selector, and dark mode toggle for good measure. Since the version list will be dynamic, we can serve up a versions.json file or something and use javascript to parse it, or we could do something with frames if we want to avoid using JS unnecessarily.~
Better idea, let's keep with sphinx, and get the docs on readthedocs. They support open source projects for free, and deal with things like versioning for us. They also support custom domains so we can still do api.angr.io, and we could set up each project to be in a subdirectory. RTD will automatically build our docs for us based on tagged releases, so I would be able to effectively remove angr-doc from the release process.
Thoughts @ltfish @rhelmot @mborgerson?
rhelmot
github-actions[bot]
We should move the api docs to their own repos instead of this one. They don't really serve a purpose being here since each file is discrete to each repo. Additionally, it is very common case requiring PR syncing that can be avoided. This is also a step towards future decoupling of angr modules.