Improving Flatpak documentation

[Jorge García]

Hi,

Another option could be adding the section in the current flatpak.org
website.

I sent a PR some days ago with a proposal and working code some days ago

https://github.com/flatpak/flatpak.github.io/pulls

Best regards,
Jorge

El dia 6 gen. 2017 4:34 p. m., "Allan Day" <allanpday at gmail.com> va
escriure:

> 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/361be1c0/attachment.html>