<div dir="ltr">On Fri, Jan 6, 2017 at 12:51 PM, Emmanuele Bassi <span dir="ltr"><<a href="mailto:ebassi@gmail.com" target="_blank">ebassi@gmail.com</a>></span> wrote:<span class="gmail-"></span><br><div class="gmail_extra"><div class="gmail_quote"><span class="gmail-"></span><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><span class="gmail-">
> The main issue I found is that search doesn't seem to work when using<br>
> MkDocs/Markdown (probably because of this [1] bug). readthedocs recommends<br>
> using Sphinx/reStructuredText [2] instead and it looks like search would<br>
> work if we ported over to use that instead. I have some reservations about<br>
> that, though.<br>
><br>
> Does anyone know of any alternatives that we should consider?<br>
<br>
</span>ReadTheDocs is certainly the current state of the art, considering the<br>
mindshare it has among various free software projects — OSTree itself<br>
has its documentation hosted there.<br>
<br>
Personally, I think the trade off to migrate from MarkDown to<br>
reStructuredText is well worth it; while MarkDown looks simpler to<br>
write, it's also a very poor representational format. reST gives you<br>
more control on the text, and has an actual syntax/validation, as<br>
opposed to an informal base grammar with a thousand and one<br>
forks/extensions on top.<br>
<br>
So I'd endorse porting the documentation to reST, and I'd gladly<br>
volunteer to help doing that.<span class="gmail-HOEnZb"><font color="#888888"><br></font></span></blockquote><div><br></div><div>I've experimented with porting some of our docs to reST and displaying them on readthedocs: <a href="http://flatpak-test.readthedocs.io/">http://flatpak-test.readthedocs.io/</a><br><br></div><div>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.<br><br></div><div>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.)<br><br></div><div>Allan<br> </div></div><br></div></div>