All-Hands-AI
Create Documentation Site
Summary
The goal of this issue is to propose a first documentation concept to iterate on and start a discussion around this topic.
Motivation
As the Project grows it would be helpful to have a good documentation, especially for new contributors and users. The documentation has to contain all neccessary information while still beeing easy to use and maintain.
Technical Design
TL;DR Create a seperate repository "OpenDevin/OpenDevinDocs" for documentation, containing autogenerated code documentation and manually created parts (Overview, architecture, examples)
Generation and content The documentation should at least contain the following contents:
- High-level project overview
- Installation instructions, How-To Guide, Examples
- Architectural diagrams
- API documentation
- Generated code documentation
This means documentation will consist of two parts: An autogenerated code documentation Part which is generated by GitHub actions on every commit/PR and a part for which has to be maintained manually, but less frequently.
Versioning / Repository The documentation should be stored in a seperate repository (e.g. OpenDevin/OpenDevinDocs) This enables tracking documentation-related issues separately, keeping the main repository focused on development. It would also be possible to implement the same branch concept as in the code repository by automatically creating a docs branch for each code branch.
Separation between Frontend and Backend Pro seperation: Frontend and backend use very different technology stacks. A seperation allows it to use better suited tools for each part. Con seperation: Frontend and Backend are part of the same project, so the documentation should also consider both parts for a better understanding of the project as a whole. Proposal: Store frontend and backend docs in the same repository with a root-level separation (similar to the code repository). Then docs for frontend and backend can be generated separately and maybe can be tied together with an index site for navigation between both parts.
Tooling For Backend: Use Sphinx due to its wide usage and extensive configurability. For Frontend: TBD.
Documentation Format HTML for best readability/design and compatibility for hosting on various platforms.
Hosting Sphinx generates HTML files which can be hosted for example on GitHub Pages or readthedocs.
Alternatives to Consider
Additional Context
This page provides a good guideline on the content of a project documentation https://coderefinery.github.io/documentation/wishlist/
We will definitely need a docs site at some point, so I think it makes sense to keep it open.
@jannikwinghart IMO we should keep the docs within this repo for now. It's much simpler to manage everything in one place. I could be convinced otherwise though.
In my opinion the main constraints regarding docs generation and storage should be:
- Don't flood the source repo with autogenerated docs html files (increases repo size, leads to many "irrelevant" changes in each PR, etc.)
- Don't build the docs locally, build process has to happen in the CI-Pipeline (no time consuming pre-commit hooks, don't introduce additional toolchain requirements for contributors)
In case we want to use github pages for hosting (or similar static html hosting sites), we would need to generate all html files and push them to a repo which then can be hosted. In this case I would prefer to use a seperate repo to fulfill the constraints above.
The other option (which I also like after reading into it) is to not generate and store the html files on our end, but instead use a service like readthedocs for generation and hosting of the docs files. readthedocs builds and stores the html files on their servers completely, so our repo would only contain the documentation "source" files (sphinx rst, etc.), and no autogenerated html files.
At least for the python part this would be a clean solution, even though I'm not quite sure yet if docs for the tsx/frontend part can be integrated easily.
Possible downside on this option is that the docs build process (and possible errors) is not visible for everybody, only for the readthedocs project maintainers (unlike github actions).