Improving Flatpak documentation

[Emmanuele Bassi]

HI Allan;

On 6 January 2017 at 12:36, Allan Day <allanpday at gmail.com> wrote:

> We don't have much web maintenance capacity, so whatever option we go for
> needs to be quick and easy to setup. readthedocs is an obvious option.
> Yesterday I had a go at putting our existing Markdown docs into it:
> http://flatpak.readthedocs.io/en/latest/
>
> It's certainly easy to setup and has good integration with Github - you just
> push your changes to the Git repo and the documentation automatically
> updates. People can also download your docs, and you can version them.
>
> The main issue I found is that search doesn't seem to work when using
> MkDocs/Markdown (probably because of this [1] bug). readthedocs recommends
> using Sphinx/reStructuredText [2] instead and it looks like search would
> work if we ported over to use that instead. I have some reservations about
> that, though.
>
> Does anyone know of any alternatives that we should consider?

ReadTheDocs is certainly the current state of the art, considering the
mindshare it has among various free software projects — OSTree itself
has its documentation hosted there.

Personally, I think the trade off to migrate from MarkDown to
reStructuredText is well worth it; while MarkDown looks simpler to
write, it's also a very poor representational format. reST gives you
more control on the text, and has an actual syntax/validation, as
opposed to an informal base grammar with a thousand and one
forks/extensions on top.

So I'd endorse porting the documentation to reST, and I'd gladly
volunteer to help doing that.

Ciao,
 Emmanuele.

-- 
https://www.bassi.io
[@] ebassi [@gmail.com]