Improving Flatpak documentation

[Allan Day]

On Wed, Nov 23, 2016 at 4:24 PM, Allan Day <allanpday at gmail.com> wrote:
>
> I propose to improve the main flatpak website adding a  documentation
>> section, something like Angular's website
>> <https://angular.io/docs/ts/latest/>, or Ionic Framework
>> <https://ionicframework.com/docs/v2/> or create a manual at readthedocs
>> like OStree. <https://ostree.readthedocs.io/en/latest/> (some of the
>> information in flatpak's wiki is in Markdown already so most of the effort
>> won't be wasted)
>>
>> I can help setting up the things (readthedocs, jekyll, ...) and
>> organizing a little bit the docs, but I would like to have some help (I'm
>> not a native English speaker)
>>
>> What do you think?
>>
>
> As time goes on it is likely that we will need a more advanced method for
> hosting and organisatiing the developer docs [1]. Are we at the point where
> we need to do that? I'm not sure.
>

Having thought about this some more, I think I agree that we need something
more sophisticated for hosting our documentation. It would help to have a
way to quickly navigate between sections, and a multi-page approach would
be more sustainable than a single big tutorial. Search would also be good.

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?

Allan

[1] https://github.com/rtfd/readthedocs.org/issues/1487
[2] http://www.sphinx-doc.org/en/1.5.1/index.html
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.freedesktop.org/archives/flatpak/attachments/20170106/81a929e1/attachment.html>