Improving Flatpak documentation

[Allan Day]

On Fri, Jan 6, 2017 at 12:51 PM, Emmanuele Bassi <ebassi at gmail.com> wrote:

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

I've experimented with porting some of our docs to reST and displaying them
on readthedocs: http://flatpak-test.readthedocs.io/

You can see that search works on this instance. The reST syntax is fairly
straightforward and I'd be happy to port the rest of our docs to use it.

We might want a way to test changes locally before pushing them. This would
(I assume) require that we setup the documentation repository to use
Sphinx. It would also require that we have documentation maintainers who
are happy to use Sphinx to locally validate the docs. (The alternative, I
suppose, would be to live dangerously and use the readthedocs instance to
check that everything is rendering as it should.)

Allan
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.freedesktop.org/archives/flatpak/attachments/20170106/a1d31370/attachment.html>