Move API docs to project repos. about angr-doc HOT 5 CLOSED

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?

from angr-doc.

Summary from an offline discussion:

go for it dude

from angr-doc.

This issue has been marked as stale because it has no recent activity. Please comment or add the pinned tag to prevent this issue from being closed.

from angr-doc.

This issue has been marked as stale because it has no recent activity. Please comment or add the pinned tag to prevent this issue from being closed.

from angr-doc.

This is complete! Took less than a year, even.

from angr-doc.