Documentation: Add 'furo' theme

[tobiasdiez]

As discussed in #33309 comment:28, we add Furo (https://pradyunsg.me/furo/) as a possible theme for the documentation.
After gaining some experience with it, the goal would be to make it the default theme for sage's docs.

To test, run

make furo
make doc-clean; make doc-uninstall; make

To go back to the classic sage theme, uninstall furo using ./sage -pip uninstall furo.

Known issues (to be fixed as follow-ups/upstream):

• Reference manual index page and many sub-pagaes don't have a table of contents on the left https://516dfe85b21eafae4f042320e5dcf61ad14fe780--sagemath-tobias.netlify.app/reference/
• Index page is missing/not working https://516dfe85b21eafae4f042320e5dcf61ad14fe780--sagemath-tobias.netlify.app/
• sage logo in the side bar should link to the top of the Sage manuals

Depends on #25833
Depends on #33740

CC: @kwankyu @strogdon @haraldschilly @mkoeppe

Component: documentation

Author: Tobias Diez

Branch/Commit: aec8fec

Reviewer: Kwankyu Lee

Issue created by migration from https://trac.sagemath.org/ticket/33601

[tobiasdiez]

comment:1

There are still some problems with the reference and tutorial (something with static directories that are not found, any help appreciated), but the developer doc seems to work fine already. Feedback welcome!

Question: Is it correct that one has to add each dependency in the dependency tree as a sage package?

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

cc0f093

Use furo on ci

[sagetrac-git]

Changed commit from 67f1279 to cc0f093

[mkoeppe]

comment:3

Replying to @tobiasdiez:

Question: Is it correct that one has to add each dependency in the dependency tree as a sage package?

Yes if you make furo a "normal" package as in your current branch.
You can avoid it by making it a "pip" package instead.
https://doc.sagemath.org/html/en/developer/packaging.html#package-source-types

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

3be9522	Make furo a pip package
c0bd95a	Fix intend

[sagetrac-git]

Changed commit from cc0f093 to c0bd95a

[tobiasdiez]

comment:5

Replying to @mkoeppe:

Replying to @tobiasdiez:

Question: Is it correct that one has to add each dependency in the dependency tree as a sage package?

Yes if you make furo a "normal" package as in your current branch.
You can avoid it by making it a "pip" package instead.
https://doc.sagemath.org/html/en/developer/packaging.html#package-source-types

Okay thanks. From the docs it was not clear to me when to choice pip packages over normal ones. I made furo now a pip package and it seems to work.

I've also activated for the doc build github action, so it be visible there in a couple of hours.

[mkoeppe]

comment:7

I think it would be better to configure the theme explicitly instead of activating it whenever the package is installed. See #33320 comment:44

[sagetrac-git]

Changed commit from c0bd95a to 1ce8955

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

8e8c76b	Reactivate matplotlib
6260621	cleanup
b90316d	Configure mathjax in sphinx config
9bc4432	Migrate rest of config
1ce8955	Merge remote-tracking branch 'origin/public/docs/mathjax_ext' into public/doctests/furo

[mkoeppe]

comment:9

All dependencies of furo (https://github.com/pradyunsg/furo/blob/main/pyproject.toml#L18 and https://github.com/pradyunsg/sphinx-theme-builder/blob/main/pyproject.toml#L16) for which we have SPKGs need to be listed in dependencies. This is so that there is not a race between installing a package with our tools and the automatic installation of dependencies by pip.

[sagetrac-git]

Changed commit from 1ce8955 to 516dfe8

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

516dfe8

Try with _static folder

[tobiasdiez]

comment:11

That seems to work more or less:
https://516dfe85b21eafae4f042320e5dcf61ad14fe780--sagemath-tobias.netlify.app/reference/
https://516dfe85b21eafae4f042320e5dcf61ad14fe780--sagemath-tobias.netlify.app/tutorial/

I would propose that anyone interested can scroll around on these pages and then we can collect things that are not yet working as expected (and decide if they should be handled as part of this ticket or in followups).

[tobiasdiez]

comment:15

After merging #33616 and #33608 this is now working well for me. Ready for review.

[tobiasdiez]

Changed dependencies from #33600 to #33600, #33616, #33608

[tobiasdiez]

comment:16

Replying to @mkoeppe:

All dependencies of furo (https://github.com/pradyunsg/furo/blob/main/pyproject.toml#L18 and https://github.com/pradyunsg/sphinx-theme-builder/blob/main/pyproject.toml#L16) for which we have SPKGs need to be listed in dependencies. This is so that there is not a race between installing a package with our tools and the automatic installation of dependencies by pip.

I've added the dependencies from furo. Does the sphinx-theme-builder dependencies have to be really added? For me it downloads a wheel for furo, so build dependencies are ignored.

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

55dcb7d	Simplify inventory builder
92fb2b1	Fix indentation
908134d	Merge remote-tracking branch 'origin/public/docs/simplify_inventory_builder' into public/doctests/furo
0618873	Ensure symlink points to an existing directory
7adb904	Merge remote-tracking branch 'origin/u/klee/33608' into public/doctests/furo
2269f19	Add dependencies

[sagetrac-git]

Changed commit from 516dfe8 to 2269f19

[kwankyu]

comment:48

Replying to @kwankyu:

Unfortunately the automatic merge of Git failed in this

Technically the automatic merge didn't fail because I kept the file and the content of src/sage/docs/conf.py to prevent merge failures. Now I am not sure if I did a right thing...

[mkoeppe]

comment:49

Yes, it would have been better to just do from sage_docbuild.conf import * in the old file.

[kwankyu]

comment:50

Replying to @mkoeppe:

Yes, it would have been better to just do from sage_docbuild.conf import * in the old file.

Would it be acceptable to do this here? That is, removing all content and leaving the deprecation and the above import statement.

[mkoeppe]

comment:51

Sure, why not

[kwankyu]

comment:52

Replying to @mkoeppe:

Sure, why not

Okay. Please Tobias.

[sagetrac-git]

Changed commit from 80e39a1 to 171d2c9

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

3df515d	Small cleanup of mathjax spkg
171d2c9	Move changes to new sage_docbuild

[tobiasdiez]

comment:54

Replying to @kwankyu:

Replying to @mkoeppe:

Sure, why not

Okay. Please Tobias.

Done (if I understood it correctly).

[kwankyu]

comment:55

Replying to @tobiasdiez:

Replying to @kwankyu:

Replying to @mkoeppe:

Sure, why not

Okay. Please Tobias.

Done (if I understood it correctly).

Correct. Thanks.

Now the sage logo (at upper left corner) does not appear in furo theme.

[tobiasdiez]

comment:56

It shows correctly in the online version: https://171d2c983650a7762b8006698dcbfd00b37e5939--sagemath-tobias.netlify.app/reference/

[kwankyu]

comment:57

Okay. At least the optional furo package works. Minor problems with the furo theme could be tackled in later tickets.

[kwankyu]

Reviewer: Kwankyu Lee

[tobiasdiez]

comment:58

Thanks for the review! I've opened #33833 to keep track of the remaining issues.

[vbraun]

comment:59

Merge failure on top of:

054e8ed8d9 Trac #33316: Drop support for GCC < 6.3 in Sage 9.7

fa3b529 Trac #25833: Upgrade to MathJax 3 and configure Sage

e2ebf44 Trac #33825: Use pytest-xdist to run pytest in parallel

b400962 Trac #33824: make gens and orbits of PermutationGroup immutable

af23627 Trac #33809: some pathlib in combinat and groups

955b5d9 Trac #33803: Fixes for the distributions sagemath-objects, sagemath-categories

3e6b41f Trac #33799: Replace SAGE_TMP in doctests of sage.misc.{persist,ostools}, sage.doctest, sage.repl

a3fd718 Trac #33797: sage.misc.temporary_file: Remove use of SAGE_TMP

2ca0530 Trac #33794: modules/fp_graded/morphism.py test failure

7037fba Trac #33793: sage.misc.cython: Replace use of SPYX_TMP by a new cached function in sage.misc.temporary_file

d115270 Trac #33787: Installation manual: Update section "system-wide install"

0ae5565 Trac #33782: ci-cygwin: Update python version

833f53d Trac #33779: Remove use of SAGE_TMP in sage.interfaces.latte

b376a8d Trac #33771: SSLContext needs an argument

df168c8 Trac #33763: Refactor src/sage/docs

9597eaf Trac #33748: make accessing coefficients of finite-field elements easier

f02236f Trac #33744: Compute bases/circuits in MatroidUnion

8943dc0 Trac #33743: Faster random tree generator

773ec37 Trac #33740: Add conda dev environment

5e65c16 Trac #33734: variety() for polynomial systems over ℚ using msolve

8e7dcca Trac #33733: allow to use flint for Stirling numbers

6f4efb0 Updated SageMath version to 9.7.beta0

merge was not clean: conflicts in .vscode/settings.json

[sagetrac-git]

Changed commit from 171d2c9 to aec8fec

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. Last 10 new commits:

0716595	Add missing bootstrap and combine pip install command
10338a7	Change ci as well
0cf7334	Add sage-setup as install-requires dep
6d2b149	Use relative paths to not install src package
1dba3ba	Maybe thats the correct shebang?
c1b2fbf	Revert install_requires change
ad56ba3	Go back to two pip installs for now
b42f5f5	Readd how to use specific python version
87f360c	Readd name arg
aec8fec	Merge #33740

[mkoeppe]

comment:61

Merged #33740 to resolve merge conflict

[mkoeppe]

Changed dependencies from #25833 to #25833, #33740

[vbraun]

Changed branch from public/doctests/furo to aec8fec