
<html><head><meta http-equiv="Content-Type" content="text/html charset=utf-8"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><blockquote style="margin: 0 0 0 40px; border: none; padding: 0px;" class=""></blockquote><div class="">Thank you for putting together this proposal Richard. </div><div class=""><br class=""></div><div class="">I think you have proposed some good ways to lower the bar on documentation contributions. </div><div class=""><br class=""></div><div class="">To *really* see what your changes look like you need too build the docs. Doing this via the docker scripts isn’t too bad, but being familiar with docker is definitely too high a bar for encouraging casual doc contributions.</div><div class=""><br class=""></div><div class="">So, in lieu of that, taking maximal advantage of GitHub’s rendering of .rst is a great option.</div><div class=""><br class=""></div><div class="">By preferring more vanilla rst directives over our custom rst directives we can have our docs looking better in Github, and give contributors a better idea of what their built docs will look like.</div><div class=""><br class=""></div><div class="">And obviously getting images to render is a big win.</div><div class=""><br class=""></div><div class="">I’m not familiar with how we translate docs. Will this affect our translations in any way?</div><div class=""><br class=""></div><div class="">M</div><div class=""><br class=""></div><div class=""><br class=""><blockquote type="cite" class=""><blockquote style="margin: 0 0 0 40px; border: none; padding: 0px;" class=""></blockquote></blockquote><div class="">Thu Dec 24 13:55:58 UTC 2015 Richard Duivenvoorde richard at <a href="http://duif.net" class="">duif.net</a> :<br class=""><blockquote style="margin: 0 0 0 40px; border: none; padding: 0px;" class=""></blockquote><br class=""></div><blockquote type="cite" class=""><br class="">Hi PSC/Community,<br class=""><font color="#5856d6" class=""><br class=""></font>Because I think we should attract more people to write documentation for<br class="">QGIS, I thought we should make it easier to fix/write docs.<br class=""><font color="#5856d6" class=""><br class=""></font>My idea: let's keep our rst framework, but do the editing/viewing in<br class="">Github..<br class=""><font color="#5856d6" class=""><br class=""></font>First: look at the following two examples:<br class=""><font color="#5856d6" class=""><br class=""></font>[0]<br class=""><font color="#5856d6" class=""><br class=""></font><a href="https://github.com/FOSS4GAcademy/GST101FOSS4GLabs/blob/master/Module%204%20Lab/QGIS%202.8/Module%204%20Lab.md" class="">https://github.com/FOSS4GAcademy/GST101FOSS4GLabs/blob/master/Module%204%20Lab/QGIS%202.8/Module%204%20Lab.md</a><br class=""><font color="#5856d6" class=""><br class=""><br class=""></font>and<br class=""><font color="#5856d6" class=""><br class=""></font>[1]<br class=""><font color="#5856d6" class=""><br class=""></font>https://github.com/qgis/QGIS-Documentation/blob/master/source/docs/user_manual/working_with_vector/vector_properties.rst<br class=""><font color="#5856d6" class=""><br class=""><br class=""></font>As you can see the first one is immediately readable (and more editable)<br class="">in Github.<br class="">We have (I think from our Latex roots) a lot of extra styling<br class="">directives/stuff in our docs. It looks like this now:<br class=""><font color="#5856d6" class=""><br class=""></font>[3]<br class=""><font color="#5856d6" class=""><br class=""></font>http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector/vector_properties.html#the-vector-properties-dialog<br class=""><font color="#5856d6" class=""><br class=""><br class=""></font>I propose and tested the following:<br class=""><font color="#5856d6" class=""><br class=""></font>- move images from resources into an images directory in the source<br class="">folder, see<br class="">[4]<br class=""><font color="#5856d6" class=""><br class=""></font>https://github.com/qgis/QGIS-Documentation/tree/master_github_e/source/docs/user_manual/working_with_vector<br class=""><font color="#5856d6" class=""><br class=""><br class=""></font>- remove all the :guilabel: :menuselection: and other directives to make<br class="">it easier to edit/view in Github<br class=""><font color="#5856d6" class=""><br class=""></font>- get rid of all/most of the image/icon shortcuts (needed for inline<br class="">images) from source.conf and put them in the source file where they are used<br class=""><font color="#5856d6" class=""><br class=""></font>- remove substitutions like |qg| (for QGIS) and |nix| (for linux icon).<br class="">It clutters the source as seen on Github.<br class=""><font color="#5856d6" class=""><br class=""></font>I branched docs and changed one file, look at the Github preview now:<br class=""><font color="#5856d6" class=""><br class=""></font>[6]<br class=""><font color="#5856d6" class=""><br class=""></font>https://github.com/qgis/QGIS-Documentation/blob/master_github_e/source/docs/user_manual/working_with_vector/vector_properties.rst<br class=""><font color="#5856d6" class=""><br class=""><br class=""></font>As you can see it is the same file as the rst above [1], but here you do<br class="">not see all the :xxxx: directives, you see the images etc. Hopefully<br class="">much easier to add or fix a paragraph here.<br class=""><font color="#5856d6" class=""><br class=""></font>I did not yet move all the image substitutions but if you put those IN<br class="">the source file and point to the local image dir, you see them also in<br class="">Github.<br class=""><font color="#5856d6" class=""><br class=""></font>An example local build here next to a classic build:<br class=""><font color="#5856d6" class=""><br class=""></font>http://i.imgur.com/SjSC94N.png<br class=""><font color="#5856d6" class=""><br class=""><br class=""></font>I also build the pdf. Because style directives like :guilabel: also are<br class="">followed by text in `back quotes` it still gets a special styling:<br class="">italic in pdf and 'cite' in html<br class="">So the stuff that is now bleu in html can for example be made italic or<br class="">bold easily.<br class=""><font color="#5856d6" class=""><br class=""></font>So should I make a QEP for this.<br class="">Should I just GO?<br class="">Do people REALLY miss the extra styling?<br class=""><font color="#5856d6" class=""><br class=""></font>Otto what do you think?<br class=""><font color="#5856d6" class=""><br class=""></font>The whole plan/vision is that by looking cleaner/better in Github, it is<br class="">easier for people to edit/fix stuff in docs: so we have better<br class="">Documentation!<br class=""><font color="#5856d6" class=""><br class=""></font>Parts of it can be automated, as nobody has recent translated images<br class="">there is not so much work in resources directory.<br class="">I think we should start with the User Manual first.<br class="">Then Python Cookbook, then Training Manual..<br class=""><font color="#5856d6" class=""><br class=""></font>Regards,<br class=""><font color="#5856d6" class=""><br class=""></font>Richard Duivenvoorde<br class=""><font color="#5856d6" class=""><br class=""></font>PS, part 2 of all this is to fix some styling in the sphinx templates:<br class="">remove bootstrap so hopefully it is easier to use docs in Webkit-widgets<br class="">again (an early attempt in processing failed, I think because bootstrap<br class=""><div class="">uses to much javascript magic to make content responsive)..</div></blockquote></div><span class=""></span><div class=""><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""></blockquote></span><span class=""><blockquote type="cite" class=""><br class=""></blockquote></span><span class=""><br class=""></span></div></body></html>