Proposal: make Furo a standard package

[Kwankyu Lee]

Dear Sage developers,

Furo is a clean customisable Sphinx documentation theme. It has been an optional pip package since  Sage 9.7.beta2.

Meanwhile we made efforts to make Furo a new theme for our documentation through 

https://trac.sagemath.org/ticket/33601

https://trac.sagemath.org/ticket/34252

https://trac.sagemath.org/ticket/33833

Now it is ready to replace the current Sage classic theme that makes our documentation look awfully outdated. You can check the documentation with new look and feel in 

https://2505ea042169d8a179d4b1f28a0c0baeabdd421a--sagemath-tobias.netlify.app/

It would be great that Sage 9.7 will be released with the lifted-up documentation. 

So we propose here to upgrade the Furo package to a standard package. Please vote.

[Vincent Delecroix]

Thanks for working on this. +1 for making Furo standard.

Let me add a note that I don't like so much the code blocks (ie
EXAMPLES/TESTS). Namely,
* the brackets and parenthesis are weirdly bold (maybe because of the
fonts on my computer)
* numbers appear in bold blue and we basically see only this from far away
* I dislike the output part being in italic
* The "sage:" prompt has the same color as comments "# this is a
comment" which is not nice
* The symbols +, *, / have too close color to prompt and commands

Best
Vincent

> --
> You received this message because you are subscribed to the Google Groups "sage-devel" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/sage-devel/f0478d5c-6005-4a30-b96e-5b9b2e37b213n%40googlegroups.com.

[Kwankyu Lee]

On Thursday, August 4, 2022 at 2:07:56 PM UTC+9 vdelecroix wrote:

Let me add a note that I don't like so much the code blocks (ie
EXAMPLES/TESTS). Namely,
* the brackets and parenthesis are weirdly bold (maybe because of the
fonts on my computer)
* numbers appear in bold blue and we basically see only this from far away
* I dislike the output part being in italic
* The "sage:" prompt has the same color as comments "# this is a
comment" which is not nice
* The symbols +, *, / have too close color to prompt and commands

The style of code blocks is dictated by the Pygments style in Sphinx. What you see is the "tango" style, which seems best from my experiments. 

Here are the choices: https://pygments.org/styles/ You may like other style But it would be hard to pick one style agreeable to us all. 

Later we may make our own Pygments style that best suits Sage. 

 

[Vincent Delecroix]

Is it your personal decision to use tango for the (future) sage
documentation? As a very personal opinion, I prefer better the default
style. Note that tango is a style with lower contrast which is another
argument against it.

Vincent

[Kwankyu Lee]

Is it your personal decision to use tango for the (future) sage documentation?

Yes.

 

As a very personal opinion, I prefer better the default style. 

Note that tango is a style with lower contrast which is another argument against it.

Okay. As far as I know, currently these are preliminary candidates for preferred pygments style: "default", "sphinx", and "tango". There may be more.

I do not insist my choice, and we can change this choice whenever we want. Open a ticket later. So please let us not discuss this issue now.  

[John Cremona]

Yes, please at least (1) turn off the italics for output, and (2)
don't put numbers in the input in a different colour.

For such a change I think it is appropriate and would follow precedent
to put up at least two different possible themes and ask people on
sage-devel to vote.

John

> --
> You received this message because you are subscribed to the Google Groups "sage-devel" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+...@googlegroups.com.

> To view this discussion on the web visit https://groups.google.com/d/msgid/sage-devel/3750de2a-cd5a-4c88-9fae-109dda2df3a0n%40googlegroups.com.

[Kwankyu Lee]

On Thursday, August 4, 2022 at 4:46:59 PM UTC+9 john.c...@gmail.com wrote:

Yes, please at least (1) turn off the italics for output, and (2)
don't put numbers in the input in a different colour.

For such a change I think it is appropriate and would follow precedent
to put up at least two different possible themes and ask people on
sage-devel to vote.

Okay. See the new thread for polling.

[Dima Pasechnik]

On Thu, 4 Aug 2022, 02:29 Kwankyu Lee, <ekwa...@gmail.com> wrote:

Dear Sage developers,

Furo is a clean customisable Sphinx documentation theme. It has been an optional pip package since  Sage 9.7.beta2.

Meanwhile we made efforts to make Furo a new theme for our documentation through 

https://trac.sagemath.org/ticket/33601

https://trac.sagemath.org/ticket/34252

https://trac.sagemath.org/ticket/33833

Now it is ready to replace the current Sage classic theme that makes our documentation look awfully outdated. You can check the documentation with new look and feel in 

maybe I used Sage for too long, but I am fine with current layout, and I find the look in the example URL too bland, and less clearly separating code and non-code. 

Can we hear about advantages of furo beyond "look" ?

I don't at all mind having your layout as an option, needless to say.

https://2505ea042169d8a179d4b1f28a0c0baeabdd421a--sagemath-tobias.netlify.app/

It would be great that Sage 9.7 will be released with the lifted-up documentation. 

So we propose here to upgrade the Furo package to a standard package. Please vote.

--
You received this message because you are subscribed to the Google Groups "sage-devel" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/sage-devel/f0478d5c-6005-4a30-b96e-5b9b2e37b213n%40googlegroups.com.

[David Joyner]

On Wed, Aug 3, 2022 at 9:29 PM Kwankyu Lee <ekwa...@gmail.com> wrote:
>
> Dear Sage developers,
>
> Furo is a clean customisable Sphinx documentation theme. It has been an optional pip package since Sage 9.7.beta2.
>
> Meanwhile we made efforts to make Furo a new theme for our documentation through
>
> https://trac.sagemath.org/ticket/33601
> https://trac.sagemath.org/ticket/34252
> https://trac.sagemath.org/ticket/33833
>
> Now it is ready to replace the current Sage classic theme that makes our documentation look awfully outdated. You can check the documentation with new look and feel in
>
> https://2505ea042169d8a179d4b1f28a0c0baeabdd421a--sagemath-tobias.netlify.app/
>

This seems to allow dark mode when viewed in a browser on a cellphone,
which the old documentation did not seem to allow. I'm not sure how
important that is to users though.

> It would be great that Sage 9.7 will be released with the lifted-up documentation.
>
> So we propose here to upgrade the Furo package to a standard package. Please vote.
>
>
>
>
>
>
>

[Kwankyu Lee]

On Thursday, August 4, 2022 at 8:46:28 PM UTC+9 David Joyner wrote:

This seems to allow dark mode when viewed in a browser on a cellphone,
which the old documentation did not seem to allow. 

Yes. The dark mode and the responsive design  are some of the strong points of the Furo theme! 

[Eric Gourgoulhon]

Le jeudi 4 août 2022 à 03:29:07 UTC+2, Kwankyu Lee a écrit :

So we propose here to upgrade the Furo package to a standard package. Please vote.

+1

Thanks for working on this.

Eric.

[David Roe]

+1 for Furo as standard from me as well.

David

 

Eric.

--
You received this message because you are subscribed to the Google Groups "sage-devel" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/sage-devel/2d4c3a31-6375-425a-aee3-3a0c6810aa41n%40googlegroups.com.

[dmo...@deductivepress.ca]

+1 from me, too.  Thanks for doing this.

[Kwankyu Lee]

Up to now, there were 

4 positive, 

1 implicitly positive, 

1 implicitly negative 

votes. Thank you who voted. I think it is safe to conclude that the standard Furo package is accepted. 

The new standard package enables the new doc in Furo theme, which will be the default in the next sage release.

If you want to use the new doc for your ticket, then merge #33833 to your ticket.  

Thank you all.