[Qgis-community-team] QGIS docs: Vanilla build & ReadTheDocs theme

classic Classic list List threaded Threaded
15 messages Options
Reply | Threaded
Open this post in threaded view
|

[Qgis-community-team] QGIS docs: Vanilla build & ReadTheDocs theme

Richard Duivenvoorde
For those interested,

We've been playing around with a more vanilla use of Sphinx to build the
documentation:

1) because the transifex (and hopefull Github) integration should be
better now with newer Sphinx (not ready yet)
2) to make it possible for EVERYBODY to build the docs on both Windows,
Linux (and probably also Macs) by creating an Python virtual env and run
the default Sphinx make/bat file
3) because the vanilla ReadTheDocs theme is responsive.

If you want to test, I made a little pet-project:

https://github.com/rduivenvoorde/qgisdoc

With a very small subset of the manual, so a quick build.

I also did a full (english) build and uploaded here:

https://qgis.org/test/en/

Still need some styling stuff and work to make it possible to switch
between versions and languages.

Not sure if I want to do the pdf generation again, but we could if we
want (as on the source nothing has changed).

All this to give nobody an excuse to build and write documentation :-)

Regards & let us know what you think,

Richard Duivenvoorde
_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

Re: [Qgis-community-team] QGIS docs: Vanilla build & ReadTheDocs theme

Alexandre Neto
Thanks!! 

I will definitely check it out. 

Thanks for the work. 

Alex

A sex, 15/03/2019, 20:03, Richard Duivenvoorde <[hidden email]> escreveu:
For those interested,

We've been playing around with a more vanilla use of Sphinx to build the
documentation:

1) because the transifex (and hopefull Github) integration should be
better now with newer Sphinx (not ready yet)
2) to make it possible for EVERYBODY to build the docs on both Windows,
Linux (and probably also Macs) by creating an Python virtual env and run
the default Sphinx make/bat file
3) because the vanilla ReadTheDocs theme is responsive.

If you want to test, I made a little pet-project:

https://github.com/rduivenvoorde/qgisdoc

With a very small subset of the manual, so a quick build.

I also did a full (english) build and uploaded here:

https://qgis.org/test/en/

Still need some styling stuff and work to make it possible to switch
between versions and languages.

Not sure if I want to do the pdf generation again, but we could if we
want (as on the source nothing has changed).

All this to give nobody an excuse to build and write documentation :-)

Regards & let us know what you think,

Richard Duivenvoorde
_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
--
Alexandre Neto
---------------------
@AlexNetoGeo
http://gisunchained.wordpress.com

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

Re: [Qgis-community-team] QGIS docs: Vanilla build & ReadTheDocs theme

DelazJ
Hi Richard,
Thanks for your testing. I really like it and after years it visually refreshes our documentation.
I have some issues I don't know whether I should raise them in the doc repo or here.
Here they are:

- The |updatedisclaimer| does not seem to be substituted
- I think we should better set the margin in the TOC (the local content one) between two different levels: see eg, spacing between "Symbology properties" and "Band rendering" and same between the latter and "Multiband color" at https://qgis.org/test/en/docs/user_manual/working_with_raster/raster_properties.html I think we should either keep the same space or reduce it as we go into details, ie distance "Sources properties <-> Symbology properties" >=  "Symbology properties <-> Band rendering" which is >= "band rendering <-> "Multiband color"
- Still in the above page, it could be nice to have some spacing between the "path" and the "View page source" button
- I like in the left panel the display of the sections of the chapter current chapter (a long standing issue report in the repo) and the highlighting of the active section. I also like this frame being visible all the time. However, I think it should be scrollable since if I'm eg at https://qgis.org/test/en/docs/user_manual/working_with_vector/vector_properties.html#symbology-properties there's no easy way I could get back to qgis gui chapter (at least on my 17" screen); the selected chapter was moved at the top of the unscrollable area.
- While I like the general soft coloring of the docs, I'm a bit dubious on the background coloring of Processing parameters and sub parameters (https://qgis.org/test/en/docs/user_manual/processing_algs/qgis/networkanalysis.html). Sorry, no proposal yet.
- Also it's hard imho to quickly identify the algorithms  (where they start or end); maybe should we have a bigger top marging for algorithm name. I know I've always complained about how aerate is our Processing algs docs, a bit of aeration on top of alg name wouldn't make me unhappy.

Once again, despite all the issues reported above, I really like the path we are taking. Thanks to you.

Regards,
Harrissou



Le ven. 15 mars 2019 à 21:44, Alexandre Neto <[hidden email]> a écrit :
Thanks!! 

I will definitely check it out. 

Thanks for the work. 

Alex

A sex, 15/03/2019, 20:03, Richard Duivenvoorde <[hidden email]> escreveu:
For those interested,

We've been playing around with a more vanilla use of Sphinx to build the
documentation:

1) because the transifex (and hopefull Github) integration should be
better now with newer Sphinx (not ready yet)
2) to make it possible for EVERYBODY to build the docs on both Windows,
Linux (and probably also Macs) by creating an Python virtual env and run
the default Sphinx make/bat file
3) because the vanilla ReadTheDocs theme is responsive.

If you want to test, I made a little pet-project:

https://github.com/rduivenvoorde/qgisdoc

With a very small subset of the manual, so a quick build.

I also did a full (english) build and uploaded here:

https://qgis.org/test/en/

Still need some styling stuff and work to make it possible to switch
between versions and languages.

Not sure if I want to do the pdf generation again, but we could if we
want (as on the source nothing has changed).

All this to give nobody an excuse to build and write documentation :-)

Regards & let us know what you think,

Richard Duivenvoorde
_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
--
Alexandre Neto
---------------------
@AlexNetoGeo
http://gisunchained.wordpress.com
_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

Re: [Qgis-community-team] QGIS docs: Vanilla build & ReadTheDocs theme

Richard Duivenvoorde
Hi H,

Yeah, definitely needs more work, this is really the vanilla rtd
(ReadTheDocs) theme, besides your points, I also dislike some colors
etc. But the great thing is that do not need designers/css guru's to
make the responsive stuff work etc. Changing some fonts or colors should
be doable.

Your issues (feel free to put them as issues in github):
- updatedisclaimer: probably because I've been playing with moving the
static folder... (see other thread). I was actually hoping to remove it
all the way, and use some javascript to 'inject or remove' such msg.
- about marges & spaces: mmm, have to look into it, such details are
hard to fix (as these are very flexible layouts) but I prefer to keep
this kind of details as is and maybe change our rst if possible to more
fit your idea
- with me it IS scrollable with the mouse middle button? ALternative is
to SHOW a scrollbar which is often ugly?
- coloring: yes, agreed

First we have to decide IF we want to move to this layout (as we can
easily add it to current build too!).

Maybe we can setup a small online doc team meeting this week in an
evening, to speak about and hammer some descisions?

Regards,

Richard


On 18/03/2019 08.05, DelazJ wrote:

> Hi Richard,
> Thanks for your testing. I really like it and after years it visually
> refreshes our documentation.
> I have some issues I don't know whether I should raise them in the doc
> repo or here.
> Here they are:
>
> - The |updatedisclaimer| does not seem to be substituted
> - I think we should better set the margin in the TOC (the local content
> one) between two different levels: see eg, spacing between "Symbology
> properties" and "Band rendering" and same between the latter and
> "Multiband color" at
> https://qgis.org/test/en/docs/user_manual/working_with_raster/raster_properties.html
> I think we should either keep the same space or reduce it as we go into
> details, ie distance "Sources properties <-> Symbology properties" >= 
> "Symbology properties <-> Band rendering" which is >= "band rendering
> <-> "Multiband color"
> - Still in the above page, it could be nice to have some spacing between
> the "path" and the "View page source" button
> - I like in the left panel the display of the sections of the chapter
> current chapter (a long standing issue report in the repo) and the
> highlighting of the active section. I also like this frame being visible
> all the time. However, I think it should be scrollable since if I'm eg
> at
> https://qgis.org/test/en/docs/user_manual/working_with_vector/vector_properties.html#symbology-properties
> there's no easy way I could get back to qgis gui chapter (at least on my
> 17" screen); the selected chapter was moved at the top of the
> unscrollable area.
> - While I like the general soft coloring of the docs, I'm a bit dubious
> on the background coloring of Processing parameters and sub parameters
> (https://qgis.org/test/en/docs/user_manual/processing_algs/qgis/networkanalysis.html).
> Sorry, no proposal yet.
> - Also it's hard imho to quickly identify the algorithms  (where they
> start or end); maybe should we have a bigger top marging for algorithm
> name. I know I've always complained about how aerate is our Processing
> algs docs, a bit of aeration on top of alg name wouldn't make me unhappy.
>
> Once again, despite all the issues reported above, I really like the
> path we are taking. Thanks to you.
>
> Regards,
> Harrissou
>
>
>
> Le ven. 15 mars 2019 à 21:44, Alexandre Neto <[hidden email]
> <mailto:[hidden email]>> a écrit :
>
>     Thanks!! 
>
>     I will definitely check it out. 
>
>     Thanks for the work. 
>
>     Alex
>
>     A sex, 15/03/2019, 20:03, Richard Duivenvoorde <[hidden email]
>     <mailto:[hidden email]>> escreveu:
>
>         For those interested,
>
>         We've been playing around with a more vanilla use of Sphinx to
>         build the
>         documentation:
>
>         1) because the transifex (and hopefull Github) integration should be
>         better now with newer Sphinx (not ready yet)
>         2) to make it possible for EVERYBODY to build the docs on both
>         Windows,
>         Linux (and probably also Macs) by creating an Python virtual env
>         and run
>         the default Sphinx make/bat file
>         3) because the vanilla ReadTheDocs theme is responsive.
>
>         If you want to test, I made a little pet-project:
>
>         https://github.com/rduivenvoorde/qgisdoc
>
>         With a very small subset of the manual, so a quick build.
>
>         I also did a full (english) build and uploaded here:
>
>         https://qgis.org/test/en/
>
>         Still need some styling stuff and work to make it possible to switch
>         between versions and languages.
>
>         Not sure if I want to do the pdf generation again, but we could
>         if we
>         want (as on the source nothing has changed).
>
>         All this to give nobody an excuse to build and write
>         documentation :-)
>
>         Regards & let us know what you think,
>
>         Richard Duivenvoorde
>         _______________________________________________
>         Qgis-community-team mailing list for organizing community
>         resources such as documentation, translation etc..
>         [hidden email]
>         <mailto:[hidden email]>
>         https://lists.osgeo.org/mailman/listinfo/qgis-community-team
>
>     --
>     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..
>     [hidden email]
>     <mailto:[hidden email]>
>     https://lists.osgeo.org/mailman/listinfo/qgis-community-team
>

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

Re: [Qgis-community-team] QGIS docs: Vanilla build & ReadTheDocs theme

ghtmtt
In reply to this post by Richard Duivenvoorde
Hi Richard,

thanks to have set up the demo.

I really like the idea of the vanilla rtd theme, clean simple and
responsive.

As Harrissou said there are some tweaks to do (+1 to have the subchapter
list available in the panel, updatedisclamer, some colors maybe?).

But I really like it!

Do you know if there is a way to make the left sidebar collapsible with
a button (like gitLAB sidebars)? This (maybe) could help to save some
space on some middle screen computer.

Cheers and thanks again

Let me know if/how to help

Matteo
_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

Re: [Qgis-community-team] QGIS docs: Vanilla build & ReadTheDocs theme

ghtmtt
In reply to this post by Richard Duivenvoorde
Hi Richard (again),

> First we have to decide IF we want to move to this layout (as we can
> easily add it to current build too!).

should we maybe vote for this?

> Maybe we can setup a small online doc team meeting this week in an
> evening, to speak about and hammer some descisions?

+1 for me

Matteo
_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

Re: [Qgis-community-team] QGIS docs: Vanilla build & ReadTheDocs theme

Alexandre Neto
Hi, I would refrain to change the looks of it right away. 

I also have my list of improvements for that, but I think it would be better to stabilize the usage of the theme and it's options first, and then do the improvements on top of that. 

Besides, you probably know that already, but there's a way to separate our theme tweaks from the original read the docs theme. We really need to do it the right way so we can update the theme whenever we need. 

Related subject: we talked about splitting the QGIS docs content. Will we keep using sphinx for the static content? 

If so, and assuming we are going to use the same theme, it would be better to share it via submodele, otherwise, any theme tweak must be replicated twice. 

Alexandre Neto 

A seg, 18/03/2019, 07:47, matteo <[hidden email]> escreveu:
Hi Richard (again),

> First we have to decide IF we want to move to this layout (as we can
> easily add it to current build too!).

should we maybe vote for this?

> Maybe we can setup a small online doc team meeting this week in an
> evening, to speak about and hammer some descisions?

+1 for me

Matteo
_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
--
Alexandre Neto
---------------------
@AlexNetoGeo
http://gisunchained.wordpress.com

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

Re: [Qgis-community-team] QGIS docs: Vanilla build & ReadTheDocs theme

Richard Duivenvoorde
On 2019-03-18 09:13, Alexandre Neto wrote:
> Hi, I would refrain to change the looks of it right away.
> I also have my list of improvements for that, but I think it would be
> better to stabilize the usage of the theme and it's options first, and
> then do the improvements on top of that.

+1

> Besides, you probably know that already, but there's a way to separate
> our theme tweaks from the original read the docs theme. We really need
> to do it the right way so we can update the theme whenever we need.
>
> Related subject: we talked about splitting the QGIS docs content. Will
> we keep using sphinx for the static content?
>
> If so, and assuming we are going to use the same theme, it would be
> better to share it via submodele, otherwise, any theme tweak must be
> replicated twice.

Yes, but (to me) one reason to split was because I thought to make the
python cookbook testable it would be better.
I'm still ok to split (in QGIS version specific and non version specific
docs), but the immidiate need to me is over now (as we do it now it is
just a rather quick and easy build?).
I'd like to:
- move to the rtd theme
- make translations sync work
- handle the windows build to work good with make.bat (so some static
copying)
But can be done in steps too

Richard
_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

Re: [Qgis-community-team] QGIS docs: Vanilla build & ReadTheDocs theme

ghtmtt
In reply to this post by Alexandre Neto
Hi Alexandre,

> I also have my list of improvements for that, but I think it would be
> better to stabilize the usage of the theme and it's options first, and
> then do the improvements on top of that.

+1

> Besides, you probably know that already, but there's a way to separate
> our theme tweaks from the original read the docs theme. We really need
> to do it the right way so we can update the theme whenever we need.

I don't have direct experience with that, but for other stuff I use you
have a separate `custom` folder where you put custom css and js so that
they will not be overwritten by a theme update

> Related subject: we talked about splitting the QGIS docs content. Will
> we keep using sphinx for the static content? 
>
> If so, and assuming we are going to use the same theme, it would be
> better to share it via submodele, otherwise, any theme tweak must be
> replicated twice.

we are in the middle of many different changes in the doc (too many in a
short time :) ).

But yes, personally I'm in favor of splitting the docs (static vs
dynamic) as we discussed. So you are suggesting to use git submodules?
Do you have experience in maintaining them?

Cheer and thanks

Matteo
_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

Re: [Qgis-community-team] QGIS docs: Vanilla build & ReadTheDocs theme

Alexandre Neto
Hi matteo,

On Mon, Mar 18, 2019 at 8:37 AM matteo <[hidden email]> wrote:

I don't have direct experience with that, but for other stuff I use you
have a separate `custom` folder where you put custom css and js so that
they will not be overwritten by a theme update

I will have to study it, some of my colleagues have been doing that recently so I can pick their brains for a while. The important is not mess with the readthedocs theme directly, otherwise we will be stuff with this version again for a very long time...
 
But yes, personally I'm in favor of splitting the docs (static vs
dynamic) as we discussed. So you are suggesting to use git submodules?
Do you have experience in maintaining them?


Yes, and yes. That is what I have implemented at Boundless, because we use the same theme for many different projects. it's very easy to maintain. At least easier than trying to keep the theme in all projects looking the same without it.

Anyway, let's table that for later, when we have a "final" vanilla.

Alex
 
Cheer and thanks

Matteo

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

Re: [Qgis-community-team] QGIS docs: Vanilla build & ReadTheDocs theme

Alexandre Neto
In reply to this post by Richard Duivenvoorde
Sounds good to me.

IIRC, The docs split was not related to the PyCookbook testing. We can run tests on them as they are.

The split would just remove some of the static stuff the guidelines. We don't need guideline for different versions. And even the Gentle introduction to GIS, that could be version, we are not updating it regularly, but we have it replicated for each version of QGIS we release.

On Mon, Mar 18, 2019 at 11:35 AM Richard Duivenvoorde <[hidden email]> wrote:
On 2019-03-18 09:13, Alexandre Neto wrote:
> Hi, I would refrain to change the looks of it right away.
> I also have my list of improvements for that, but I think it would be
> better to stabilize the usage of the theme and it's options first, and
> then do the improvements on top of that.

+1

> Besides, you probably know that already, but there's a way to separate
> our theme tweaks from the original read the docs theme. We really need
> to do it the right way so we can update the theme whenever we need.
>
> Related subject: we talked about splitting the QGIS docs content. Will
> we keep using sphinx for the static content?
>
> If so, and assuming we are going to use the same theme, it would be
> better to share it via submodele, otherwise, any theme tweak must be
> replicated twice.

Yes, but (to me) one reason to split was because I thought to make the
python cookbook testable it would be better.
I'm still ok to split (in QGIS version specific and non version specific
docs), but the immidiate need to me is over now (as we do it now it is
just a rather quick and easy build?).
I'd like to:
- move to the rtd theme
- make translations sync work
- handle the windows build to work good with make.bat (so some static
copying)
But can be done in steps too

Richard

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

Re: [Qgis-community-team] QGIS docs: Vanilla build & ReadTheDocs theme

Ian Maddaus
I've successfully built the new documentation using a Mac. A Mac user would have to install Xcode but that's not a big problem.


‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐
On Monday, March 18, 2019 7:40 AM, Alexandre Neto <[hidden email]> wrote:

Sounds good to me.

IIRC, The docs split was not related to the PyCookbook testing. We can run tests on them as they are.

The split would just remove some of the static stuff the guidelines. We don't need guideline for different versions. And even the Gentle introduction to GIS, that could be version, we are not updating it regularly, but we have it replicated for each version of QGIS we release.

On Mon, Mar 18, 2019 at 11:35 AM Richard Duivenvoorde <[hidden email]> wrote:
On 2019-03-18 09:13, Alexandre Neto wrote:
> Hi, I would refrain to change the looks of it right away.
> I also have my list of improvements for that, but I think it would be
> better to stabilize the usage of the theme and it's options first, and
> then do the improvements on top of that.

+1

> Besides, you probably know that already, but there's a way to separate
> our theme tweaks from the original read the docs theme. We really need
> to do it the right way so we can update the theme whenever we need.
>
> Related subject: we talked about splitting the QGIS docs content. Will
> we keep using sphinx for the static content?
>
> If so, and assuming we are going to use the same theme, it would be
> better to share it via submodele, otherwise, any theme tweak must be
> replicated twice.

Yes, but (to me) one reason to split was because I thought to make the
python cookbook testable it would be better.
I'm still ok to split (in QGIS version specific and non version specific
docs), but the immidiate need to me is over now (as we do it now it is
just a rather quick and easy build?).
I'd like to:
- move to the rtd theme
- make translations sync work
- handle the windows build to work good with make.bat (so some static
copying)
But can be done in steps too

Richard


_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

Re: [Qgis-community-team] QGIS docs: Vanilla build & ReadTheDocs theme

Alexandre Neto
That is good to know. we should had that xcode information to our writing guidelines and Readme. 

Alex

A seg, 18/03/2019, 16:40, Ian Maddaus <[hidden email]> escreveu:
I've successfully built the new documentation using a Mac. A Mac user would have to install Xcode but that's not a big problem.


‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐
On Monday, March 18, 2019 7:40 AM, Alexandre Neto <[hidden email]> wrote:

Sounds good to me.

IIRC, The docs split was not related to the PyCookbook testing. We can run tests on them as they are.

The split would just remove some of the static stuff the guidelines. We don't need guideline for different versions. And even the Gentle introduction to GIS, that could be version, we are not updating it regularly, but we have it replicated for each version of QGIS we release.

On Mon, Mar 18, 2019 at 11:35 AM Richard Duivenvoorde <[hidden email]> wrote:
On 2019-03-18 09:13, Alexandre Neto wrote:
> Hi, I would refrain to change the looks of it right away.
> I also have my list of improvements for that, but I think it would be
> better to stabilize the usage of the theme and it's options first, and
> then do the improvements on top of that.

+1

> Besides, you probably know that already, but there's a way to separate
> our theme tweaks from the original read the docs theme. We really need
> to do it the right way so we can update the theme whenever we need.
>
> Related subject: we talked about splitting the QGIS docs content. Will
> we keep using sphinx for the static content?
>
> If so, and assuming we are going to use the same theme, it would be
> better to share it via submodele, otherwise, any theme tweak must be
> replicated twice.

Yes, but (to me) one reason to split was because I thought to make the
python cookbook testable it would be better.
I'm still ok to split (in QGIS version specific and non version specific
docs), but the immidiate need to me is over now (as we do it now it is
just a rather quick and easy build?).
I'd like to:
- move to the rtd theme
- make translations sync work
- handle the windows build to work good with make.bat (so some static
copying)
But can be done in steps too

Richard

--
Alexandre Neto
---------------------
@AlexNetoGeo
http://gisunchained.wordpress.com

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

Re: [Qgis-community-team] QGIS docs: Vanilla build & ReadTheDocs theme

Anita Graser
Hi Richard,

I think the ReadTheDocs theme is a huge improvement. Just comparing https://docs.qgis.org/testing/en/docs/pyqgis_developer_cookbook/loadlayer.html to https://qgis.org/test/en/docs/pyqgis_developer_cookbook/loadlayer.html shows how much more readable the code samples are.

Are there any blockers to rolling it out?

Regards,
Anita


On Mon, Mar 18, 2019 at 6:23 PM Alexandre Neto <[hidden email]> wrote:
That is good to know. we should had that xcode information to our writing guidelines and Readme. 

Alex

A seg, 18/03/2019, 16:40, Ian Maddaus <[hidden email]> escreveu:
I've successfully built the new documentation using a Mac. A Mac user would have to install Xcode but that's not a big problem.


‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐
On Monday, March 18, 2019 7:40 AM, Alexandre Neto <[hidden email]> wrote:

Sounds good to me.

IIRC, The docs split was not related to the PyCookbook testing. We can run tests on them as they are.

The split would just remove some of the static stuff the guidelines. We don't need guideline for different versions. And even the Gentle introduction to GIS, that could be version, we are not updating it regularly, but we have it replicated for each version of QGIS we release.

On Mon, Mar 18, 2019 at 11:35 AM Richard Duivenvoorde <[hidden email]> wrote:
On 2019-03-18 09:13, Alexandre Neto wrote:
> Hi, I would refrain to change the looks of it right away.
> I also have my list of improvements for that, but I think it would be
> better to stabilize the usage of the theme and it's options first, and
> then do the improvements on top of that.

+1

> Besides, you probably know that already, but there's a way to separate
> our theme tweaks from the original read the docs theme. We really need
> to do it the right way so we can update the theme whenever we need.
>
> Related subject: we talked about splitting the QGIS docs content. Will
> we keep using sphinx for the static content?
>
> If so, and assuming we are going to use the same theme, it would be
> better to share it via submodele, otherwise, any theme tweak must be
> replicated twice.

Yes, but (to me) one reason to split was because I thought to make the
python cookbook testable it would be better.
I'm still ok to split (in QGIS version specific and non version specific
docs), but the immidiate need to me is over now (as we do it now it is
just a rather quick and easy build?).
I'd like to:
- move to the rtd theme
- make translations sync work
- handle the windows build to work good with make.bat (so some static
copying)
But can be done in steps too

Richard

--
Alexandre Neto
---------------------
@AlexNetoGeo
http://gisunchained.wordpress.com
_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

Re: [Qgis-community-team] QGIS docs: Vanilla build & ReadTheDocs theme

DelazJ
Hi all,

Le sam. 25 mai 2019 à 19:39, Anita Graser <[hidden email]> a écrit :
Hi Richard,

I think the ReadTheDocs theme is a huge improvement. Just comparing https://docs.qgis.org/testing/en/docs/pyqgis_developer_cookbook/loadlayer.html to https://qgis.org/test/en/docs/pyqgis_developer_cookbook/loadlayer.html shows how much more readable the code samples are.

Indeed the difference is significant. I wonder if we should not use the whole width of the screen in order to fully see codes and comments without horizontal scrolling

Are there any blockers to rolling it out?

I think the plan was/is to set a repository and have people test and report issues (I have reported some in this thread) or pull request to ensure that we lose nothing in the migration. IOW it needs some more testing and feedback from community.


Regards,
Anita


On Mon, Mar 18, 2019 at 6:23 PM Alexandre Neto <[hidden email]> wrote:
That is good to know. we should had that xcode information to our writing guidelines and Readme. 

Alex

A seg, 18/03/2019, 16:40, Ian Maddaus <[hidden email]> escreveu:
I've successfully built the new documentation using a Mac. A Mac user would have to install Xcode but that's not a big problem.

Ian do you think that you can spend some time on writing about this in the readme? It could be nice we have instructions for macOS users.

Regards,
Harrissou


‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐
On Monday, March 18, 2019 7:40 AM, Alexandre Neto <[hidden email]> wrote:

Sounds good to me.

IIRC, The docs split was not related to the PyCookbook testing. We can run tests on them as they are.

The split would just remove some of the static stuff the guidelines. We don't need guideline for different versions. And even the Gentle introduction to GIS, that could be version, we are not updating it regularly, but we have it replicated for each version of QGIS we release.

On Mon, Mar 18, 2019 at 11:35 AM Richard Duivenvoorde <[hidden email]> wrote:
On 2019-03-18 09:13, Alexandre Neto wrote:
> Hi, I would refrain to change the looks of it right away.
> I also have my list of improvements for that, but I think it would be
> better to stabilize the usage of the theme and it's options first, and
> then do the improvements on top of that.

+1

> Besides, you probably know that already, but there's a way to separate
> our theme tweaks from the original read the docs theme. We really need
> to do it the right way so we can update the theme whenever we need.
>
> Related subject: we talked about splitting the QGIS docs content. Will
> we keep using sphinx for the static content?
>
> If so, and assuming we are going to use the same theme, it would be
> better to share it via submodele, otherwise, any theme tweak must be
> replicated twice.

Yes, but (to me) one reason to split was because I thought to make the
python cookbook testable it would be better.
I'm still ok to split (in QGIS version specific and non version specific
docs), but the immidiate need to me is over now (as we do it now it is
just a rather quick and easy build?).
I'd like to:
- move to the rtd theme
- make translations sync work
- handle the windows build to work good with make.bat (so some static
copying)
But can be done in steps too

Richard

--
Alexandre Neto
---------------------
@AlexNetoGeo
http://gisunchained.wordpress.com
_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team