Small refactoring of the Training Manual answers

[ghtmtt]

QGIS Enhancement: Title

Date 2021-02-04

Author Matteo Ghetta (@ghtmtt)

Contact matteo dot ghetta at gmail dot com

maintainer @ghtmtt

Version QGIS 3

Summary

This isn't a QGIS QEP rather a QGIS Documentation QEP.

Many Training Manual files give the chance to the users to test their ability with a question and the text provides an anchor to the correct answer: https://docs.qgis.org/3.10/en/docs/training_manual/basic_map/overview.html#basic-ty-2

The answers are located in another rst file that has anchors to get back to the original text: https://docs.qgis.org/3.10/en/docs/training_manual/answers/answers.html#interface-overview-2

We have therefore to pay attention to different files and to a lot of anchors.

From the user point of view it is less confusing to bounce between different files and have the question and answer in the same page.

Proposed Solution

The proposal aims to add an embedded solution admonition directly in all the original rst files. The custom admonition is treated by sphinx like the other standard admonition (note, warning, tip).

Some small css rules have to be added with a small js code snippet that extends the page.html file.

The code snippet for writer is like the following:

.. only:: html

    ..  admonition:: Solution
        :class: toggle

         The text here.... 

         Eventually code

         .. code-block:: python

            My code content

         Or images:

         .. figure:: img/gui_numbered.png
            :align: center

Example(s)

A before and after example:

Before

After

Affected Files

qgis_docs.css layout.html

Performance Implications

None

Further Considerations/Improvements

For newcomers it could be simpler to add examples.

Backwards Compatibility

None

Votes

(required)

[ghtmtt]

@DelazJ @rduivenvoorde @SrNetoChan

[rduivenvoorde]

@ghtmtt I like the idea (when doing this on a computer).

Some things to think about:

• if we take them out of the other rst, what will happen when you
  • print this out (will the answers be visible? I think they should as then at least people can hide them)
  • have a simple browser or js disabled (idem: I think they should be visible then)

Another option: yes do it: who needs printouts or old browsers anyway :-)

Is the training manual being a little maintained nowadays? I've seen some questions around it in the mailing list.

[ghtmtt]

@rduivenvoorde in both browsers without js enabled and in static files (like pdf) the solution text is visible and not collapsed

Is the training manual being a little maintained nowadays? I've seen some questions around it in the mailing list.

we had some PR recently, but it needs some love :)

[SrNetoChan]

I am all up to simplifying the workload. So +1 for putting the solution in the same page as the question. For printouts you can use a

.. only:: html and .. only:: pdf

Not sure about old browsers @rduivenvoorde , I don't use one of those for years!!!

[DelazJ]

From the user point of view it is less confusing to bounce between different files and have the question and answer in the same page

Even for "advanced" writers, it's hard to track answer for update/fix. So Having the answer close to the questions would really help. How does it play with PDF (not necessarily printed)? I think most of our users use the PDF for the training.

Is the training manual being a little maintained nowadays?

Yes a little. Just updated a chapter this week-end. BTW the PR is still open for review...

[ghtmtt]

Even for "advanced" writers, it's hard to track answer for update/fix.

yep, the idea is to help both writers and users

So Having the answer close to the questions would really help. How does it play with PDF (not necessarily printed)? I think most of our users use the PDF for the training.

I'm having some latex issue with QGIS Docs, but here a screenshot of another file:

[ghtmtt]

@SrNetoChan @rduivenvoorde @DelazJ can I proceed? Do you have other questions?

[SrNetoChan]

Fine by me.

[rduivenvoorde]

Yep: go

[SrNetoChan]

@ghtmtt can you warn us when you have a working example?

[DelazJ]

@ghtmtt So in pdf, the solution would be displayed as plain text below the question if I correctly get the screenshot. Right? I don't know if it's better (I'm not used to teaching) but I assume there's no (easy?) way we could make the solution frame collapsible in PDF. Anyway, from a writer pov, it's a win. And from a html reader/lecturer, it would be also. Time for people to download our Html zipped folder 😁 and use it for the exercises (and if it's really, really annoying, we could probably resurrect the one page answers and use the .. include role to populate it, only for PDF. But we are not yet there, just some food) And yes, please go ahead and let us know when you have a prototype. Thanks.

[ghtmtt]

So in pdf, the solution would be displayed as plain text below the question if I correctly get the screenshot. Right?

correct. There will be a box with the plain text of the solution as it is in the screenshot

I don't know if it's better (I'm not used to teaching) but I assume there's no (easy?) way we could make the solution frame collapsible in PDF.

I didn't find any. :(

Anyway, from a writer pov, it's a win. And from a html reader/lecturer, it would be also. Time for people to download our Html zipped folder grin and use it for the exercises (and if it's really, really annoying, we could probably resurrect the one page answers and use the .. include role to populate it, only for PDF. But we are not yet there, just some food)

yes, this is also what I think: a win win for writer and readers and YES, let's get rid of pdf and let people download a local html copy of our wonderful readthedoc documentation :)

And yes, please go ahead and let us know when you have a prototype. Thanks.

yep. I plan to make a small PR with all the theme files addition (css, js, etc) and just a single chapter with the updated structure. So you all can checkout the PR and share your thoughts

[ghtmtt]

implemented. Thanks to all the reviewers and testers