<div dir="ltr">On 27 August 2016 at 01:09, Nicholas Bishop <span dir="ltr"><<a href="mailto:nbishop@neverware.com" target="_blank">nbishop@neverware.com</a>></span> wrote:<br><div class="gmail_extra"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><div>Hi,</div><div><br></div><div>I'd like to propose a conversion of Mesa's documentation to reStructuredText (RST) and hosting the result on <a href="http://readthedocs.org" target="_blank">readthedocs.org</a>. The intent is to make Mesa's documentation more accessible, searchable, and easier to edit.</div><div><br></div><div>I put together a quick proof-of-concept here:</div><div><br></div><div>    <a href="http://mesa-docs.readthedocs.io/en/latest/intro.html" target="_blank">http://mesa-docs.readthedocs.<wbr>io/en/latest/intro.html</a></div><div><br></div><div>    (For comparison: <a href="http://mesa3d.org/intro.html" target="_blank">http://mesa3d.org/intro.html</a>)</div><div><br></div><div>Readthedocs.org essentially renders either Markdown or RST from a git repository (or other VCS) into a nice pretty set of HTML pages. (I'm more familiar with Markdown than RST, but I saw the Gallium docs are already using RST on <a href="http://readthedocs.org" target="_blank">readthedocs.org</a>.)</div><div><br></div><div>Putting the content in RST and on <a href="http://readthedocs.org" target="_blank">readthedocs.org</a> makes formatting and searching easy, and it's a familiar platform for many developers.</div><div><br></div><div>For the linked proof-of-concept I used pandoc (<a href="http://pandoc.org/" target="_blank">http://pandoc.org/</a>) to convert all the HTML pages to RST, on top of which I did some minor editing to make the table of contents look reasonable. It's by no means a finished conversion, but I hope having something to look at can make discussion easier. This is all just a few hours work, but of course proofing and correcting all the text/formatting would take somewhat longer.</div><div><br></div><div>Here's the git repo that <a href="http://readthedocs.org" target="_blank">readthedocs.org</a> is pulling from:</div><div><a href="https://github.com/nicholasbishop/mesa-docs/tree/master/docs" target="_blank">https://github.com/<wbr>nicholasbishop/mesa-docs/tree/<wbr>master/docs</a></div><div><br></div><div>Thoughts?</div></div></div></blockquote><div><br></div><div>Hello Nicholas,<br><br></div><div>Although not a core Mesa developer, I have recently done work on Mesa documentation.<br><br></div><div>So FWIW, in my view this is a worthwhile objective to work towards <a href="http://readthedocs.org">readthedocs.org</a> formatted documentation. It is clear and well presented. We also have precedence within this project for using that service, for the Gallium docs in RST.<br><br></div><div>Worth considering however:<br><br></div><div>1. How can we minimize the effort of maintaining two repositories? (I don't think anyone here would support dropping the HTML docs, as they feed into the main Mesa website).<br>2. How easy it is to automate the additional tweaks you mention? Scriptable?<br></div><div><br></div><div>Rhys<br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><span class="HOEnZb"><font color="#888888"><div><br></div><div>-Nicholas</div></font></span></div><div><br></div></div>
<br>______________________________<wbr>_________________<br>
mesa-dev mailing list<br>
<a href="mailto:mesa-dev@lists.freedesktop.org">mesa-dev@lists.freedesktop.org</a><br>
<a href="https://lists.freedesktop.org/mailman/listinfo/mesa-dev" rel="noreferrer" target="_blank">https://lists.freedesktop.org/<wbr>mailman/listinfo/mesa-dev</a><br>
<br></blockquote></div><br></div></div>