Repository navigation
DOC Website for PyRIT #362
Description
Describe the issue linked to the documentation
PyRIT currently does not have a website to make documentation easier to discover and interact with.
Suggest a potential alternative/fix
PyRIT should have an auto-generated website. Options include sphinx, mkdocs, jupyterbook. The key difference is that jupyterbook uses MyST, mkdocs uses markdown, and sphinx allows markdown, MyST, and reStructured Text (reST). Jupyterbook builds on top of sphinx. For an extensive comparison between the two refer to this page. Jupyterbook also has a neat integration for ipynb files which is currently our entire documentation. For that reason, I'm inclined to suggest going that route unless we hit any roadblocks.
Example: interpret.ml uses jupyter books with MyST
Version management should ideally be taken care of by ReadTheDocs since it's by far the simplest. https://docs.readthedocs.io/en/stable/examples.html
Individual tasks:
- basic jupyterbooks setup working, i.e., there's a folder from which we generate the website, a config file, and the workflow is documented (commands for generating it, dependencies, etc.)
- The pyrit package code auto-generates an API reference. This may result in tons of issues or warnings that need to be addressed as well (for example, the current docstrings may be formatted badly).
- The existing docs folder needs to be integrated into this website as our user guide / examples. Interestingly, unlike many other projects we can't have all our notebooks execute upon doc build; or at least not currently (because it involves lots of LLM calls which the automated doc build would not be able to handle). Instead, the pre-generated and checked in notebooks should be displayed on the website. There must be a config option for that.
- The website needs a nice landing page.
- The website needs to be
integrated with ReadTheDocs for versioning.versioned. -
The website needs to be integrated with GitHub pipelines to show previews on PRs (that preview the changes). https://github.com/readthedocs/actions/tree/main/previewnot strictly needed
Note: in the past we've explored having only a wiki page but that wasn't really discoverable for people.
Activity
Ashleycodesseo commentedon Sep 18, 2024
Hey Roman Lutz (@romanlutz) if you need help with documentation I'd be happy to assist. I'm looking to get some experience with REST API documentation so please let me know in what way I can give you a hand. Thanks
romanlutz commentedon Sep 19, 2024
cngo20 and Sam (@sf-msft) came up with the basic jupyterbooks setup.
We don't really have REST APIs right now as there's no service. You're welcome to check the existing docstrings and see if you can make them better/clearer (or ask questions if they are unclear!), of course. That's a somewhat different task from setting up the website infrastructure (which is what this task is about), though.
romanlutz commentedon Mar 5, 2025
If anyone has thoughts on the landing page I'm all ears. The ReadTheDocs work needs to be done by one of the maintainers.
romanlutz commentedon Jun 19, 2025
Update: we shouldn't do custom work on the landing page as jupyterbook2 (JB2), the next gen rebuilt version of JB, is solving that for us. They don't have API reference support yet, though, so that will be something to sort out first.
Related:
jupyter-book/mystmd#1858
jupyter-book/mystmd#1259
jupyter-book/mystmd#293
The ReST vs MyST conflict has in the past encouraged me to explore migrating from autodoc to autodoc2 for API reference documentation BUT it didn't work out because autodoc2 appears to have loads of other limitations. That's why I'm excited about a MyST-based solution for this rather than a sphinx-based one that won't work with JB2 anyway.
Similarly, JB2 should help with #807 (which I failed with in #864 )