[Qgis-community-team] Report of QGIS documentation meeting
Richard Duivenvoorde
rdmailings at duif.net
Sat Mar 23 08:54:01 PDT 2019
Thanks Alexandre,
So now we can start theming :-) ...
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])
-3- same for :file: with is now a sort of alias-style for 'fixed-space
literal'
-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.
Please have a look at github pages and gitlab pages below, and build
yourself to see what it looks now. Also play with source.conf options if
you want.
Also feel free to disagree :-)
Regards,
Richard Duivenvoorde
[0] https://github.com/rduivenvoorde/qgisdoc/
[1] https://gitlab.com/rduivenvoorde/qgisdoc/
[3]
https://gitlab.com/rduivenvoorde/qgisdoc/blob/master/source/docs/user_manual/trans.rst
[4]
https://gitub.com/rduivenvoorde/qgisdoc/blob/master/source/docs/user_manual/trans.rst
On 23/03/2019 01.39, Alexandre Neto wrote:
> Hi all,
>
> I just created a rtd_qgis theme based Read the Docs and used it in the
> conf.py. I believe this is the way we should customize RTD themes
> without disrupting it. I haven't done it, but we can also replace HTML
> files to add stuff like the language selector somewhere.
>
> https://github.com/rduivenvoorde/qgisdoc/pull/3
>
> This is what I have used for inspiration:
>
> https://www.sphinx-doc.org/en/master/theming.html
> https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html#theme-options
>
> Cheers,
>
> Alex Neto
>
>
>
> Alexandre Neto <senhor.neto at gmail.com <mailto:senhor.neto at gmail.com>>
> escreveu no dia sexta, 22/03/2019 às 20:01:
>
> Hi!
>
> Sorry for such a short presence, I though the meeting was set to GMT...
>
> I would like to follow up the sphinx-theme customization. I will
> study the sphinx way of nesting theme so we can alway update the
> read the docs theme and put our customization on top of it.
>
> Best regards,
>
> Alex
>
>
> A sex, 22/03/2019, 16:35, matteo <matteo.ghetta at gmail.com
> <mailto:matteo.ghetta at gmail.com>> escreveu:
>
> Hi all,
>
> here a brief summary of the meeting we had:
>
> * we will wait another week to push the translated resources of the
> documentation of 3.4. We are waiting for the new transifex-github
> integration method that should make things easier, but it seems
> hard to
> put it in production
>
> * get rid of the pdf documents but still provide downloadable
> resources
> for online use as html zip file (for every language). Reasons: pdf
> builder is not easy to maintain, heavy resources asking while
> with html
> we have the same builder (we just need to create the zip files)
> and html
> are usable offline together with QGIS (interactive links and
> help buttons)
>
> * change doc theme to vanilla-rdt. There are still some issues
> and fix
> to make, but we (thanks Richard) have already something online
> [0]. We
> will work from time to time to fix all the issues and then
> publish it
>
> * splitting the main repository into different ones (static vs
> dynamic)
> is not a priority for now. There seems not to be blockers with the
> current environment that works fine
>
> * we still have some redirection issues of the main website (3.0 and
> 3.4). If someone is wiling to help Richard with apache and/or
> Tudor with
> nginx is more than welcome
>
> * this meeting was a great success: I think it is the first
> documentation meeting of the QGIS history (?) so we thought that
> it is a
> good habit to do this "often" (every 2 months or of course every
> time is
> needed)
>
> Thanks to all the participants!
>
> Cheers
>
> Matteo
>
>
>
> [0] https://qgis.org/test/en/docs/index.html
> _______________________________________________
> Qgis-community-team mailing list for organizing community
> resources such as documentation, translation etc..
> Qgis-community-team at lists.osgeo.org
> <mailto:Qgis-community-team at lists.osgeo.org>
> https://lists.osgeo.org/mailman/listinfo/qgis-community-team
>
> --
> Alexandre Neto
> ---------------------
> @AlexNetoGeo
> http://sigsemgrilhetas.wordpress.com
> http://gisunchained.wordpress.com
>
> --
> Alexandre Neto
> ---------------------
> @AlexNetoGeo
> http://sigsemgrilhetas.wordpress.com
> http://gisunchained.wordpress.com
>
> _______________________________________________
> Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
> Qgis-community-team at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/qgis-community-team
>
More information about the Qgis-community-team
mailing list