Make furo sage standard doc theme

[tobiasdiez]

In #33601, the furo theme has been introduced for the documentation. The aim of this ticket is to make it the standard theme. Before it happens, the remaining issues need to be fixed:

• Index page in double columns look awful -- fixed in Make index page single column #34265
• sage logo in the side bar should link to the top of the Sage manuals - fixed in Revive furo #34252
• no link to the doc root - fixed in Add a Home link to the doc root #34267
• search page not working - fixed in Revive furo #34252
• "ERROR: Adding a table of contents in Furo-based documentation is unnecessary" - https://73e5aa3fbbec2d751a47064c14479fc0d55c3de9--sagemath-tobias.netlify.app/installation/source.html#installation-in-a-multiuser-environment - fixed in Remove toc warnings #34262

To support this ticket, the standard Furo package was accepted by the voting done in

• https://groups.google.com/g/sage-devel/c/VTU_I-ecPlA

along with subsidiary votings in

• https://groups.google.com/g/sage-devel/c/eRh16v5Mz0c
• https://groups.google.com/g/sage-devel/c/rhPECxe128o

Other possible improvements:

• Install sphinx-hoverxref, sphinx-notfound-page (see setuptools documentation, which also uses furo - https://setuptools.pypa.io/en/latest/history.html#documentation-changes)

Depends on #34252
Depends on #34262
Depends on #34265
Depends on #34267
Depends on #34450

CC: @kwankyu @strogdon @haraldschilly @mkoeppe

Component: documentation

Author: Kwankyu Lee, Matthias Koeppe

Branch/Commit: 1f03957

Reviewer: Matthias Koeppe, Kwankyu Lee

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

[kwankyu]

Author: Kwankyu Lee

[kwankyu]

Branch: u/klee/33833

[sagetrac-git]

Commit: e5b1f7e

[sagetrac-git]

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

9d1e07a	Revive furo
f19b597	Add link to the logo
09d5f5c	Fix the logo link for reference
ae75d53	Fix a subtle reference problem for build_options
3519bed	Run docbuild workflow with single thread
1274718	Fix a suspicious part of categories doc
e5b1f7e	Add search.html

[kwankyu]

Dependencies: #34252

[kwankyu]

Changed branch from u/klee/33833 to none

[kwankyu]

Changed author from Kwankyu Lee to none

[kwankyu]

Changed commit from e5b1f7e to none

[kwankyu]

Changed dependencies from #34252 to none

[mkoeppe]

comment:13

It looks like that after these refinements, the new theme may be ready to become standard. How about a sage-devel vote?

[kwankyu]

Branch: u/klee/make-furo-standard-theme

[kwankyu]

Commit: 79e7ff7

[kwankyu]

comment:16

I don't see this a problem:

• 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/ ​

and removed it.

---

Last 10 new commits:

ebd3b77	Better pygments style
73e5aa3	Make white logo transparent to match with furo
183e558	Merge branch 'develop' into t/34252/revive-furo
40377a6	Make single column index page
c99c280	Add a Home link to the doc root
bf04b5d	Merge branch 't/34267/add_a_home_link_to_the_doc_root' into make-furo-standard-theme
49a9316	Remove toc warnings
16cbb44	Take care of a missed toc directive
502fe68	Merge branch 't/34262/remove_toc_warnings' into make-furo-standard-theme
79e7ff7	Make furo sage standard sphinx theme

[kwankyu]

comment:65

Replying to @mkoeppe:

Sorry that I forgot about that when I reviewed the ticket!

The policy should be mentioned here:

https://doc.sagemath.org/html/en/developer/packaging.html#prerequisites-for-new-standard-packages

[kwankyu]

comment:66

Then could it be that furo is still the default when we build sage from source?

[mkoeppe]

comment:67

We'd need to add the Python packages that are needed for building furo from source. But I'm not sure if that solves the problem completely because one of these dependencies is nodeenv, which suggests that the build process may also need to fetch Javascript packages.

[mkoeppe]

comment:68

I'd suggest that we back out the change to "standard" from this ticket and pursue the path to make it a standard normal package on a separate ticket

[sagetrac-git]

Changed commit from 666e90d to fe77168

[sagetrac-git]

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

480837b	build/pkgs/nodeenv: Change to standard (sphinx_theme_builder dependency)
e830650	build/pkgs/rich: New
1d5c5ca	build/pkgs/commonmark: New (dependency of rich)
39ceec8	build/pkgs/typing_extensions: Update to 4.3.0
3516e51	build/pkgs/sphinx_theme_builder: New
b1cdacd	build/pkgs/pyproject_metadata: New
345c019	build/pkgs/pyproject_metadata/dependencies: Update
8da3288	Merge #34449
611453c	build/pkgs/pyproject_metadata: Update to 0.6.1
fe77168	build/pkgs/nodeenv: Change to a standard normal package

[mkoeppe]

comment:70

Anyway here's the branch with all the dependencies - and it does have the problem that I thought:

[furo-2022.6.21] Building wheels for collected packages: furo
[furo-2022.6.21]   Building wheel for furo (pyproject.toml): started
[furo-2022.6.21]   Running command Building wheel for furo (pyproject.toml)
[furo-2022.6.21]   [stb] # nodeenv does not exist.
[furo-2022.6.21]   [stb] # Generating new nodeenv with NodeJS 16.15.1!
[furo-2022.6.21]   [stb] $ python -m nodeenv --node=16.15.1 --prebuilt --clean-src
[furo-2022.6.21]   /Users/mkoeppe/s/sage/sage-rebasing/worktree-rebase/local/var/lib/sage/venv-pyth
[furo-2022.6.21]   on3.8/var/tmp/sage/build/furo-2022.6.21/src/.nodeenv
[furo-2022.6.21]    * Install prebuilt node (16.15.1) .
[...]
[furo-2022.6.21]   TimeoutError: [Errno 60] Operation timed out
[furo-2022.6.21] 

(it's trying to download Node.js from the internet, which fails because our installation poisons the https proxy)

[mkoeppe]

comment:71

An alternative direction would be to install furo from a wheel. We don't have a mechanism for that yet, but it would not be very hard to add.

This would avoid the complicated nodeenv business (which is only needed for from-source build of furo).

I've opened #34450 for this

[sagetrac-git]

Changed commit from fe77168 to 6f813de

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

8d90b56	build/pkgs/furo: Make it a normal package
28f30ac	build/bin/sage-spkg: Handle *.whl packages
fd1c677	build/pkgs/furo: Use a wheel
9fa490a	build/pkgs/sphinx_basic_ng: New (furo dependency)
6f813de	Merge #34450

[mkoeppe]

comment:73

Try this

[mkoeppe]

Changed dependencies from #34252, #34262, #34265, #34267 to #34252, #34262, #34265, #34267, #34450

[mkoeppe]

comment:75

Replying to @kwankyu:

Replying to @mkoeppe:

Sorry that I forgot about that when I reviewed the ticket!

The policy should be mentioned here:

https://doc.sagemath.org/html/en/developer/packaging.html#prerequisites-for-new-standard-packages

I've added it to the documentation in #34450

[kwankyu]

comment:76

Replying to @mkoeppe:

Try this

With #34421, the branch successfully builds sage and doc in furo theme from scratch.

[kwankyu]

Changed branch from u/mkoeppe/make-furo-standard-theme to u/klee/make-furo-standard-theme

[kwankyu]

Changed commit from 6f813de to 1f03957

[kwankyu]

comment:78

It works well. Thank Matthias!

---

New commits:

eba7f6f	src/doc/en/developer/packaging.rst: Document wheel packages
8e06d43	src/doc/en/developer/packaging.rst: Policy on wheels, on standard packages
b12e9dc	Use the name platform-independent
d887d44	Use rerun instead of re-run
1f03957	Merge branch 't/34450/standard_wheel_packages' into t/33833/make-furo-standard-theme

[kwankyu]

Changed reviewer from Matthias Koeppe to Matthias Koeppe, Kwankyu Lee

[kwankyu]

comment:79

The branch also passes Volker's test.

[mkoeppe]

comment:80

Great, thanks for testing!

[vbraun]

Changed branch from u/klee/make-furo-standard-theme to 1f03957