Developer documentation within the repository


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.

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.

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.

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.


  • 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
  • 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.