[Qgis-community-team] Report of QGIS documentation meeting

[Alexandre Neto]

Hi Richard et al.,

Sorry for the late reply.

On Sat, Mar 23, 2019 at 3:54 PM Richard Duivenvoorde <rdmailings at duif.net>
wrote:

> BUT BUT... what if we make it our goals to
>
> -1- to make the editing as simple as possible, that is: make it possible
> for people to 'just edit in github [0] or gitlab [1]
> -2- make it as readable as possible at git*.com too
> -3- keep it as simple as possible for (beginning) writers
>
> Then I would propose (but please correct me if I'm wrong in one or more
> items):
>
> -1- get rid of :guilabel: directive. While it is rendered in our website
> with some nice blue color (and I think historical more or less as a
> 'button'). In git*.com it is shown as an ugly textual directive:
>   Then click on :guilabel:`Classify` button
> While if we keep it simple: just do:
>   Then click on the **Classify** button
> We do not have the shiny styling possibility in your site (it will just
> be rendered *bold*) but it will make readibility/writebility in git*.com
> better.
>
> -2- same for :menuitem:
> Though if we really want to distinguish between those two (now they have
> a slightly different color of blue) we could use 'bold', 'italic' or
> 'fixed-space literal' (or a combi?... not [2][3])
>
>
- 0.1 :-P

There are many more other roles that are not rendered correctly on github.
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").

On the other hand, I am ok if a beginner does not use guilabels or
menuselections while they create content. Someone can go after and improve
that.


> -3- same for :file: with is now a sort of alias-style for 'fixed-space
> literal'
>

+0

No strong feelings about this one. Again, I don't think its use should be
mandatory, but it's ok for me.

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.

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.


> -4- use common images (in static/common) folder with relative paths.
> This would make that we do not need to (cannot) use the search-replace
> script, and as can use sources/static/common as img folder, git*.com
> will show them. I 'think' this makes it easier for writers.
> If they add a common img, they just drop it in the source/static/common
> folder (no copying/linking needed) and try out the right relative link.
> Disadvantages: we have to instruct to use the width/height attribute (in
> em units) and use common images as much as possible.
>

- 1
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)
Having people change width/heigh attributes of images manually will end up
in many different sizes throughout the documentation.


> Also feel free to disagree :-)
>

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.

On Sun, Mar 24, 2019 at 11:08 AM Richard Duivenvoorde <rdmailings at duif.net>
wrote:

> Ah, duh. Found another 'solution' for this!
>
> So the actual problem is that the Sphinx build process and the git*.com
> renderers have a different notion what '/static' means. And that is ONLY
> because we have the static and conf.py in a separate /source folder...
> So we can also just remove the source folder! Which is actually an
> option when you create a fresh sphinx project!
> See the 'nosourcedir' branch:
>
> https://github.com/rduivenvoorde/qgisdoc/blob/nosourcedir/docs/user_manual/trans.rst
>
>
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.



> For the inline substitutions to work we have 2 options:
> 1) use current master scenario: a script finds all substitution keys
> from rst files, and adds them based on substitutions.txt to the rst
> files bottom, so the git*.com renderers have them at hand and can show
> them.
> 2) declare every 'common' image 'substitution' again in the rst file it
> is being used
>
>
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.

Best regards,

Alex
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-community-team/attachments/20190326/8b3df3da/attachment.html>