Summary
Add doc` directories to plinth and inner django modules. Write developer documentation in GH-flavored markdown format.
This convention of shipping developer documentation within the repository can be followed in other FreedomBox projects as well.
Problem
The developer documentation on the wiki at Manual/Developer hasn’t been updated in years.
The documentation being maintained in a separate wiki and not being in version control is a classic anti-pattern we have to avoid.
A lot of design decisions and implementation details are spread across git commit messages and GitLab issues, neither of which are easy to refer to during development.
Solution
Keep developer documentation in version control and included within the repository that it’s relevant to.
This documentation can explain design decisions, implementation plan, tech debt etc.
Individual app modules can have their own doc directory since they might be shipped independently in the future. The outer plinth module itself can also have a doc directory which contains more general documentation like “how to create a FreedomBox app”.
(We already have a doc directory at root of the Plinth repository which contains the user manual extracted from the wiki.)
Merge requests can be raised with documentation included.
Alternatives
Having the documentation in a directory with markdown files keeps it independent of the git web tool we use as compared to using GitLab wiki.
It also allows offline and version-controlled historical references.
Tasks
Import the current developer documentation from Debian wiki
Convert to GH-flavored markdown format using pandoc (this allows for easy reading directly on GitLab)
Commit the .md files under plinth/doc
Write any new developer documentation in the relevant files in doc directories.
I agree with the idea that developer documentation should be documented in the code. We could tweak your plan a bit more:
Use Sphinx for documentation. This will produce documentation output in many formats. Having markdown documentation that can be browsed in source repository is not that important when we have a place online where documentation can be browsed and searched. We should be able to generate Markdown files using Sphnix if necessary. We may periodically (say every hour) publish the documentation to a site like read-the-docs, GitLab pages or something like https://dev-docs.freedombox.org/
It would be even better if the document resides with the code instead of just staying in the same repository. This is further reduces the chances of documentation getting outdated as the documentation is clearly visible from the patch. This can be done by documenting methods, classes, modules and packages. Technical plans and architecture for a subsystem can go into the module that implements the plans. In the few remaining cases, we can put the documentation into doc/ directory.
The tutorial format we adopted for writing new app can go into one of the chosen apps. We shall document the app thoroughly along with additional tutorial flow.
I have previously contributed to Armbian documentation, inline Olimex documentation, and am currently working on a documentation repository for Olimex using only mkdocs to propose to Tsvetan once I mature the layout and add content. mkdocs has been quite simple to learn and use, and I highly recommend it. Sphinx and readthedocs are quite popular, though you may have to get accustomed to writing rst files.
I am not very fond of GitHub/GitLab wikis because there is no way to link to the corresponding project repo (that I know of) without hard-coding an absolute path to include the branch name. It appears that these wikis are also able to be modified by anyone, which is great for collaboration but not good if you wish for all documentation to be vetted and deemed accurate.
For publication of highly-technical inline documentation, I would recommend pydoc, javadoc, etc, to help describe APIs and whatnot. Nothing new here.
I would be willing to dedicate some of my time working on some documentation for FreedomBox if desired, as I have been wanting to contribute to the Debian community for a while now and this may be a good way for me to do so. I would need responsive help regarding the documentation itself, however, because I am relatively new to FreedomBox.
Maybe we can do something similar to what Python and Django projects are doing. They have both API documentation within the code and a docs directory in the project where .rst files are placed. The RestructuredText format is supported by both GitLab preview (example) and also documentation generation tools like Sphinx.
Sphinx should be able to pick up and generate both long-form documentation from the docs directory and API documentation from docstrings in the source code.
For hosting the web pages, either ReadTheDocs.org or GitLab pages in Salsa (docs.freedombox.org can redirect to this) can be used. In both cases, documentation can be built and pushed with every git commit to master. ReadTheDocs has better versioning though, if we want to refer back to documentation of older versions.
This manual is available in HTML and PDF formats from the Help section of the web interface. Individual manual pages can be accessed from “Learn more…” links in each app page.
Setting up a documentation generator for API docs and technical documentation might take some time. Will update here once it is ready.