Popochiu outgrew the incubation stage and now requires better, more mature documentation that:
Provides a user experience on par with Godot itself so that users will feel at home
Can be hosted on GitHub Pages (or ReadTheDocs if we decide to use it in the future; that's where Godot's docs belong)
It's sourced from the same repository as the project itself so that we can enforce documentation writing in our Definition of Done for new features or breaking changes
It's based on MarkDown, so we can make use of the work that's already been done
Can be partially generated automatically from code comments (see #133) without breaking manual contributions
Supports switch for different engine releases/versions
Can be deployed to a subdirectory or subdomain in GHPages in case we want to add a Popochiu website at root level in the future
From a content point of view:
is LOOSELY based on the concepts of the Diataxis framework, to the larger possible extent
can be properly organized and themed depending on the project's needs
Solution description
We scouted for a solution and decided to go with MkDocs for it's natively supported by RTD and can be easily deployed on GHPages.
Also, compared to Sphinx, it uses MarkDown, and its configuration is a single YAML file.
The todo-list follows:
[x] Kickstart the docs project in the main repo
[x] Activate automation to deploy
[x] Bring the currently available documentation to the repo (split in #185)
[x] Provides instructions or presets for contributors to run MkDocs locally, if needed (docker-based solution is preferred even in Windows, but we should consider not littering the repo. Maybe a sub-repo?)
[x] Clean up the wiki or close it entirely (split in #185)
[x] Review the project's Readme to redirect to the GHPages homepage (split in #186)
Exclusions
We're not going to create a custom theme. We'll customize the logo and colors, and that's all.
Implications
This will allow contributors to add content without access to the project's wiki repo, which is way more problematic.
Benefit description
Popochiu outgrew the incubation stage and now requires better, more mature documentation that:
From a content point of view:
Solution description
We scouted for a solution and decided to go with MkDocs for it's natively supported by RTD and can be easily deployed on GHPages.
Also, compared to Sphinx, it uses MarkDown, and its configuration is a single YAML file.
The todo-list follows:
Bring the currently available documentation to the repo(split in #185)Clean up the wiki or close it entirely(split in #185)Review the project's Readme to redirect to the GHPages homepage(split in #186)Exclusions
We're not going to create a custom theme. We'll customize the logo and colors, and that's all.
Implications
This will allow contributors to add content without access to the project's wiki repo, which is way more problematic.