<div dir="ltr"><div>Hi Richard et al.,</div><div><br></div><div>Sorry for the late reply.</div><div><br></div><div><div dir="ltr" class="gmail_attr">On Sat, Mar 23, 2019 at 3:54 PM Richard Duivenvoorde <<a href="mailto:rdmailings@duif.net">rdmailings@duif.net</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
BUT BUT... what if we make it our goals to<br>
<br>
-1- to make the editing as simple as possible, that is: make it possible<br>
for people to 'just edit in github [0] or gitlab [1]<br>
-2- make it as readable as possible at git*.com too<br>
-3- keep it as simple as possible for (beginning) writers<br>
<br>
Then I would propose (but please correct me if I'm wrong in one or more<br>
items):<br>
<br>
-1- get rid of :guilabel: directive. While it is rendered in our website<br>
with some nice blue color (and I think historical more or less as a<br>
'button'). In git*.com it is shown as an ugly textual directive:<br>
  Then click on :guilabel:`Classify` button<br>
While if we keep it simple: just do:<br>
  Then click on the **Classify** button<br>
We do not have the shiny styling possibility in your site (it will just<br>
be rendered *bold*) but it will make readibility/writebility in git*.com<br>
better.<br>
<br>
-2- same for :menuitem:<br>
Though if we really want to distinguish between those two (now they have<br>
a slightly different color of blue) we could use 'bold', 'italic' or<br>
'fixed-space literal' (or a combi?... not [2][3])<br>
<br></blockquote><div><br></div><div>- 0.1 :-P<br></div><div><br></div><div><div>There are many more other roles that are not rendered correctly on <span class="gmail-gr_ gmail-gr_9 gmail-gr-alert gmail-gr_spell gmail-gr_inline_cards gmail-gr_run_anim gmail-ContextualSpelling gmail-ins-del gmail-multiReplace" id="gmail-9">github</span>. And there are many more nuances of sphinx syntax that beginners will have trouble to understand in their first tries. I don't think that stop using those will make much of a difference in term of having more contributors. Besides I kinda like that those two are rendered differently from bold or italic (no need to be blue or even inside "buttons").</div><div><br></div><div>On the other hand, I am ok if a beginner does not use <span class="gmail-gr_ gmail-gr_692 gmail-gr-alert gmail-gr_spell gmail-gr_inline_cards gmail-gr_run_anim gmail-ContextualSpelling" id="gmail-692">guilabels</span> or <span class="gmail-gr_ gmail-gr_718 gmail-gr-alert gmail-gr_spell gmail-gr_inline_cards gmail-gr_run_anim gmail-ContextualSpelling gmail-ins-del gmail-multiReplace" id="gmail-718">menuselections</span> while they create content. Someone can go after and improve that.</div><div></div></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
-3- same for :file: with is now a sort of alias-style for 'fixed-space<br>
literal'<br></blockquote><div><br></div><div>+0<br></div><div><br></div><div>No strong feelings about this one. Again, I don't think its use should be mandatory, but it's ok for me. <br></div><div><br></div><div>Now, the one I really dislike is the use of :sup: after icons. I think the output does not look very good, and it adds more complexity to the documentation. <br></div><br><div>IMHO. the only way we could really reduce the learning curve is to use plain markdown instead of rst, but I think we would lose many of sphinx power. <br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
-4- use common images (in static/common) folder with relative paths.<br>
This would make that we do not need to (cannot) use the search-replace<br>
script, and as can use sources/static/common as img folder, git*.com<br>
will show them. I 'think' this makes it easier for writers.<br>
If they add a common img, they just drop it in the source/static/common<br>
folder (no copying/linking needed) and try out the right relative link.<br>
Disadvantages: we have to instruct to use the width/height attribute (in<br>
em units) and use common images as much as possible.<br></blockquote><div><br></div><div>- 1<br></div><div>Trying to find the right relative links for each rst file is always a huge pain. (but you found a better solution already it seems (see below)<br></div><div>Having people change width/heigh attributes of images manually will end up in many different sizes throughout the documentation.<br></div><div></div><div> <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
Also feel free to disagree :-)<br></blockquote><div><br></div><div>So, I mildly disagree :-P just because I don't think changes in how we sphinx will have a true impact on having more documenters. I think the major problem for new comers (and even sporadic contributors) is the git workflow.<br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Sun, Mar 24, 2019 at 11:08 AM Richard Duivenvoorde <<a href="mailto:rdmailings@duif.net">rdmailings@duif.net</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
Ah, duh. Found another 'solution' for this!<br>
<br>
So the actual problem is that the Sphinx build process and the git*.com<br>
renderers have a different notion what '/static' means. And that is ONLY<br>
because we have the static and conf.py in a separate /source folder...<br>
So we can also just remove the source folder! Which is actually an<br>
option when you create a fresh sphinx project!<br>
See the 'nosourcedir' branch:<br>
<a href="https://github.com/rduivenvoorde/qgisdoc/blob/nosourcedir/docs/user_manual/trans.rst" rel="noreferrer" target="_blank">https://github.com/rduivenvoorde/qgisdoc/blob/nosourcedir/docs/user_manual/trans.rst</a><br>
<br></blockquote><div><br></div><div>I think we can do something even better. We can keep the source folder (which is nice to have so we know where the actual content is), and we move only the conf.py to the root. I think that will make the root of github and the project to be the same, and the root paths will work for both. I will give it a try.<br></div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
For the inline substitutions to work we have 2 options:<br>
1) use current master scenario: a script finds all substitution keys<br>
from rst files, and adds them based on substitutions.txt to the rst<br>
files bottom, so the git*.com renderers have them at hand and can show them.<br>
2) declare every 'common' image 'substitution' again in the rst file it<br>
is being used<br>
<br></blockquote><div><br></div><div>1) is actually doing 2) on demand. Documenters can manually add the common image substitution in the rst, but from time to time we can run the script to clean up unused substitutions.</div><div><br></div><div>Best regards,</div><div><br></div><div>Alex<br></div><div> </div><br></div></div>