AcademySoftwareFoundation / AcademySoftwareFoundation/OpenTimelineIO
Add documentation build and publish to github actions
- Dominant language
- C++
- Stars
- 2k
- Forks
- 351
- Avg merge
- 1d 12h
- Merged PRs (30d)
- 1
Description
Thanks to #878 we now have C++ documentation with doxygen!
There are other bits of documentation that can be generated but we don't autogenerate any of it.
We should add github actions to build documentation packages and publish the artifacts.
Note: I expect this issue will need to be broken down a lot into more manageable chunks.
## Description
The types of documentation we have/should have include:
- The hand-written markdown documentation (Tutorials, How-to guides, and Explanation)
- Auto-generated [C++ documentation](https://github.com/PixarAnimationStudios/OpenTimelineIO/tree/master/doxygen)
- Auto-generated [Python documentation](https://github.com/PixarAnimationStudios/OpenTimelineIO/blob/27adbc3c5f62aec8a2cd47b990a7f0507f48a9f2/Makefile#L167-L170)
- [Plugin documentation](https://github.com/PixarAnimationStudios/OpenTimelineIO/blob/27adbc3c5f62aec8a2cd47b990a7f0507f48a9f2/Makefile#L160-L161)
- [serialized datamodel](https://github.com/PixarAnimationStudios/OpenTimelineIO/blob/27adbc3c5f62aec8a2cd47b990a7f0507f48a9f2/Makefile#L154-L155)
- (soon) [OTIO Specification](https://github.com/OpenTimelineIO/OpenTimelineIO-Specification)
- (todo) Auto-generated (Java docs)[https://github.com/OpenTimelineIO/OpenTimelineIO-Java-Bindings)
Below is a proposed plan of attack, very open to discussion:
Currently, read the docs is compiling our markdown to html and publishing. Given that we have many documentation building systems, I suggest we migrate to an approach where we use [github pages](https://pages.github.com/) to publish most our generate documentation - the exception would be the python reference documentation which should be published to [Read the Docs](https://readthedocs.org/).
To achieve this, we should:
1. Setup the root of our github pages to host most of the content currently going to Read the Docs
2. Setup a per-language subdir in our github pages for reference docs (C++, Java, Schema, etc.)
3. Setup generation of hand-written markdown documentation to html using [MkDocs](https://www.mkdocs.org/)
4. Setup generation of each auto-generated docset as a separate artifact
5. Setup publishing generated docs to the relevant subdir in the github pages site
6. Update the Read the Docs pages to be only the python-specific material
7. Update the hand-written Markdown to link out to the generated sub-trees (or to read the docs for python)
This sets us up to have the github pages be our central documentation landing location and then users can be directed toward the information they need. Also it allows the file tree within our github pages to be namespaced out and allow many different sources to feed it.
As a trivial example, the site structure could be laid out as:
```
├── [standard mkdocs files]
├── generated
│ ├── adapters
│ ├── c++
│ ├── java
│ ├── python
│ └── specification
└── index.html
```
Then ownership of each directory under `generated` could be delegated to the actions that own publishing to those directories.
## Open Questions
- [ ] Do we want the main pages site to host bindings in "affiliated repos", or should it just link out and let them manage their own hosting?
- [ ] Is there a versioning mechanism in github pages we could take advantage of?
- [ ] How do we handle the documentation release cycle? Do we create sub-trees for individual releases, have a `latest` link, and maybe a sub-tree for the current `HEAD` version?
Contributor guide
Research direction
Review the Makefile targets referenced for Python, plugin, and serialized datamodel documentation, along with the existing Doxygen and Read the Docs flow. Break the proposal into smaller workflows and resolve the GitHub Pages layout, ownership, and release/versioning questions. Done requires agreed, actionable chunks before implementation begins.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp, github-actions, java, markdown, python
- Domain
- ci-cd, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100