Documentation for Firmware Build System

[akira25]

I'd like to have some discussion on documentation. At the moment, the documentation of the firmware is somewhat strongly dissatisfactory. New developers do not have an easy time starting developing. It think we are missing some guide which explains our build-system more detailed.

This applies especially, as our buildsystem somehow differs from the openwrt-buildsystem. Thus we shouldn't just link to that. Some (minor) example could be the repo of weimarnetz-firmware. Effectively its a fork from berlin-firmware, but they have a really nice, fairly short and easy understandable documentation in their readme-file. Especially they cover the workflow of modifying the firmware. In our readme.md this is covered very sparse. This might be a first aproach.

Instead of including all documentation in a handbook-style-document like in #809, I'd like to discuss the idea of just writing a documentation on the buildsystem using spinx as tool. Gluon writes it documentation also with that tool.

[SvenRoederer]

To separate the actual Firmware and the generic Buildsystem I created a stripped down (unpolluted by Freifunk Berlin specific stuff) branch "https://github.com/freifunk-berlin/firmware/tree/Build-System-Core". This branch can be the dedicated place to "host" the docs also and merge BuildSystem related stuff back to master.

[sarumpaet]

I'd just improve the texts first. Switching the tool to manage the documentation can come way later, if at all. Currently the problem is that no one actually works on the documentation. The tool is not the problem, be it Markdown in README files or Sphinx or whatnot.

[akira25]

I'd just improve the texts first. Switching the tool to manage the documentation can come way later, if at all. Currently the problem is that no one actually works on the documentation. The tool is not the problem, be it Markdown in README files or Sphinx or whatnot.

That's right. Actually I'd like to have a chat on markdown. I'd prefer to migrate the current README.md to reStructuredText format. I see some considerable arguments for that:

• reStructuredText supports more sophisticated use cases like references and footnotes
• In Opposition to mardown, there is only one flavour of rst files
• as it's pretty distinct, it's easy to automatically transfer it into any kind of document. (html,PDF, EPUB, LaTeX)

As there is some common set of markups in both markdown and reStructuredText, there shouldn't be too much confusion for skilled markdown-writers (further information here).

With that first step taken, we would be able to render some documentation easily in the future.

[SvenRoederer]

I'll happily support an approach to improve the documentation. Reducing the size of the top-level Readme would also be great.

As Github seems not to render .rst I see the problem tool / other external service to render the docs and have them separate from the repo.

[akira25]

I'll happily support an approach to improve the documentation. Reducing the size of the top-level Readme would also be great.

Thats a nice idea. I plan to finish #825 first and go to split the README.md into a doc-directory afterwards, with a little README.md remaining in the repositories root.
I'd like to do it that way round, so we get a first usable version rather quick, instead of including every aspect at once.

As Github seems not to render .rst I see the problem tool / other external service to render the docs and have them separate from the repo.

I agree, that there are some problems in rendering special features of rst. For example cross-references and ..note-directive (which will generate an info box in sphinx.). But besides that, the rendering of the Github-Parser looks quite robust (have an example here) and most basic linking features (like external links, etc) work properly. So a first step basic migration to rst-files should work seemlessly.

Even if we would decide to render our docs via an external tool in the future, they must not be separated from the repository. Gluon-Docs are built by read-the-docs and also reside in gluon-main-repo.

Without going to much into detail, as this is a matter for later discussion: It is possible automate the build-process of documentation to almost being autonomously (further information here).

Making a long story short: Besides some minor changes in README-syntax, there shouldn't arise any problems from switching to rst.