Make Sage documentation functional

[kwankyu]

Sage documentation (website) is currently buggy in many ways.

I tried to fix various defects I noticed, including

• links in navigation bar
• index page, which is now in single column
• sage logo link always goes to the sagemath homepage
• class names now look ragged right
• long Bases for classes now horizontally scrolled
• updated sage theme based on the latest classic theme of Sphinx
• renamed sage theme to sage-classic theme (in anticipation of alternative themes)
• remove unnecessary sageref theme; only use sage theme
• remove obsolete python2.inv hyperlinks database
• added a new index.html which is installed right into the root directory SAGE_DOC.
• adjusted colors to increase contrast among elements
• documentation access from jupyter notebook (this undoes PDF documentation links in Documentation from Jupyter notebook are broken #33206)
• search box works (turned off Thebe)

As noted in the last item above, I turned off Thebe here. Work on reviving Thebe will continue in #33320 (perhaps very slowly).

To cleanly build the new documentation, try

$ make doc-uninstall && make doc-html && make doc-pdf

CC: @strogdon @haraldschilly @mkoeppe

Component: documentation

Author: Kwankyu Lee

Branch: acecf84

Reviewer: Tobias Diez, John Palmieri, François Bissey, Steven Trogdon

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

[kwankyu]

Branch: u/klee/33309

[kwankyu]

Commit: 3b9e89f

[kwankyu]

New commits:

3b9e89f

Various fixes for sage documentation

[kwankyu]

Author: Kwankyu Lee

[sagetrac-git]

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

241ad3b

Move pdf.png to the sage theme static directory

[sagetrac-git]

Changed commit from 3b9e89f to 241ad3b

[sagetrac-git]

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

348fecb

Fix a bug in reference pdf page

[sagetrac-git]

Changed commit from 241ad3b to 348fecb

[sagetrac-git]

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

9030068

make doc-pdf rebuilds website with pdf links

[sagetrac-git]

Changed commit from 348fecb to 9030068

[tobiasdiez]

comment:18

I'm really happy to see these improvements to the documentation. What do you think about replacing sage's own theme (based on the basic theme) by something modern like furo (probably not as part of this ticket but as a follow-up)?

[jhpalmieri]

comment:19

Typo in src/doc/common/themes/sage/static/sage.css_t:

-/* this is nice, but it leads to hidden headings when jumping
+/* this is nice, but it it leads to hidden headings when jumping

[jhpalmieri]

comment:20

With OS X, the top page of the reference manual displays math correctly, but a page like https://doc.sagemath.org/html/en/reference/padics/index.html (rather, the local version) shows "(p)" throughout. This doesn't seem to be a new problem. Any ideas for a fix?

[sagetrac-git]

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

e9a24e1

Fixes in headings and for a typo

[slel]

comment:88

: )

[slel]

Changed reviewer from Tobias Diez, ... to Tobias Diez, John Palmieri, François Bissey, Steven Trogdon

[vbraun]

comment:89

Merge failure on top of:

29e12c30b2 Trac #33293: checking doctest output is too slow

3538db804f Trac #33287: make iter(ZZ^n) useful

95d62c119f Trac #33279: Put derivations over function fields in the framework of RingDerivation

a75ff8e968 Trac #33267: Improve speed of sum_of_* for CombinatorialFreeModule

a697f74ccf Trac #33261: .complement() treats bipartite graphs as generic

505e7cd991 Trac #33237: membership testing for ideals of quotient rings

b2bb4a16f9 Trac #33171: fix and activate pycodestyle E713

706626b427 Trac #33000: Remove some imports from sage.rings.all

9608d61a75 Trac #32958: findstat: enforce limit on how many elements to compute

7f5bdc5bbc Trac #32789: Fix spkg-configure.m4 for singular

8c7beae366 Trac #32465: Refactor {Matrix,Vector}_double_dense through ..._numpy_dense, add ..._numpy_integer_dense

537d9a8 Trac #31320: Coercion issue with Laurent polynomial rings

15f2fed Trac #30695: Padic slice method fails on exact zeros for certain inputs

ff40ba0 Trac #12595: Add doctest for eigenmatrix of complex floating-point matrix

e4f9347 Trac #33350: remove traces of six

24f0f4e Trac #33339: Use latest dev docker build for documentation workflow

03d78e2 Trac #32966: tox / GH Actions: Add ubuntu variants using ppa:ubuntu-toolchain-r

22221ae Trac #33174: Unreachable code in sage/graphs/base/c_graph.pyx

ddd2ab1 Trac #33163: various lgtm suggestions

83c2a60 Trac #33133: Add pictures to scatter_plot documentation

44fb492 Trac #33115: Re-run bootstrap when an install-requires.txt or package-version.txt has changed

1dda73e Trac #33110: Some performance improvements in the manifolds code

f6aff89 Trac #33035: random doctest failure in src/sage/tests/book_stein_ent.py

69ea2e5 Trac #32988: Deprecate sage.structure.graphics_file

91710c3 Trac #32912: Add pictures to disk.py

f413b85 Trac #32264: Convenience syntax for quaternion ideals

92dea6a Trac #31758: State global i or I is a number field element (and no longer in the symbolic ring)

e8c27b5 Trac #31005: Add traceback information to exceptions during docbuild

cd31b18 Trac #30763: improve setting global options to None

8b63606 Trac #24279: Remove the experimental code for RelativeFiniteFieldExtension

44cd8f8 Trac #33324: pycodestyle cleaning in discrete Fourier transforms

5791dba Trac #33314: pycodestyle cleanup of phc interface

708efc2 Trac #33307: Fix empty section display on prerequisites doc page

9a9c821 Trac #33302: fpylll might not find system-wide fplll's strategies json

c10d7bb Trac #33301: pycodestyle formatting in sage_docbuild

90ec768 Trac #33298: pycodestyle cleaning in rings/valuations/

edad8da Trac #33297: some details in src/bin scripts

01e8677 Trac #33278: Adapt Macaulay2 interface doctests to Macaulay2 1.19

d026799 Trac #33275: Bug fixes for finitely presented graded modules (#32505)

2e1f8d2 Trac #33264: Define x as symbolic variable in many animate examples

5bdf5dd Trac #33263: Add github action running on each push

959ff7a Trac #33306: tox.ini: Linux platform updates

10a3cd9 Trac #33260: Fix bug in .perfect_matchings() for BipartiteGraph

20684fe Trac #33257: fix a bug in multiple zeta values

8326dee Trac #33256: buffer.py: make files readonly only when possible

7f8b268 Trac #33123: Move construction methods to Polyhedron_base5

826061a Updated SageMath version to 9.6.beta1

merge was not clean: conflicts in src/sage_docbuild/init.py

[strogdon]

comment:90

For reference, with this branch on top of the above I see in src/sage_docbuild/__init__.py

<<<<<<< HEAD
    def pdf(self):
        """
        Install in the directory one level up to website_dir a symlink to the
        directory containing pdf files. This symlink is necessary to access
        pdf documentation files within Jupyter (see trac #33206).
        """
        super().pdf()

        html_output_dir = self._output_dir('html')
        pdf_doc_dir = os.path.join(SAGE_DOC, 'pdf')

        # relative path is preferable for symlinks
        dst = os.path.join(html_output_dir, '..')
        relpath = os.path.relpath(pdf_doc_dir, dst)
        try:
            os.symlink(relpath, os.path.join(dst, 'pdf'))
        except FileExistsError:
            pass
=======
        root_index_file = os.path.join(html_output_dir, '../../../index.html')
        shutil.copy2(os.path.join(SAGE_DOC_SRC, self.lang, 'website', 'root_index.html'),
                     root_index_file)
>>>>>>> cc0e3bf3abfb1808c32f81f15db787b83ab7ce1c

It's been a while since I've done a merge conflict, so I dare not touch it.

[kwankyu]

Changed branch from u/jhpalmieri/33309 to u/klee/33309

[kwankyu]

Changed commit from cc0e3bf to acecf84

[kwankyu]

New commits:

c3f02f4	pycodestyle formatting in sage_docbuild
1040829	more details in docbuild __init__
acecf84	Resolve merge conflict with #33301

[kwankyu]

comment:93

This ticket might be the first one to encounter with the new policy introduced recently. Namely, the ticket authors now have responsibility of resolving conflicts with the branch of the release manager. This seems so from the generated comment reporting the merge conflict above. I think this is good because this reduces the release manager's burden.

Then it would be convenient to authors and perhaps necessary that the release manager's current branch is available somewhere.

[kwankyu]

comment:94

Instead of forcing authors to resolve merge conflicts right away, they may be noticed that their branches will not be merged until after the next beta. So they can wait for the next beta and work on the merge conflicts then.

[mkoeppe]

comment:96

Replying to @kwankyu:

This ticket might be the first one to encounter with the new policy introduced recently. Namely, the ticket authors now have responsibility of resolving conflicts with the branch of the release manager.

There's no new policy; whenever the release manager encountered a merge conflict, the ticket was set back to "needs_work".

What is new is that the updated release manager scripts now provide some information regarding the conflict. Ticket authors can choose whether to address it when this comes in, or when the next beta becomes available.

[mkoeppe]

comment:97

For reference, this code is in https://github.com/sagemath/git-trac-command/blob/master/git_trac/releasemgr/app.py#L212

[kwankyu]

comment:98

Replying to @mkoeppe:

There's no new policy; whenever the release manager encountered a merge conflict, the ticket was set back to "needs_work".

What is new is that the updated release manager scripts now provide some information regarding the conflict. Ticket authors can choose whether to address it when this comes in, or when the next beta becomes available.

I was aware of the update in the release manager scripts.

I thought that previously, the merge conflict notices that I received from the release manager were always against the latest new beta, not against with the release manager's current branch that I don't have access to. But apparently I thought wrong.

[kwankyu]

comment:99

Replying to @mkoeppe:

Ticket authors can choose whether to address it when this comes in, or when the next beta becomes available.

If the author chooses to address it right away, is there an easy way to find out which ticket in the long list of the tickets has merge conflict with the present ticket? For me, it was tedious work to find this out, without access to the release manager's branch.

[slel]

comment:100

The release manager's develop branch is at:

• https://github.com/vbraun/sage/tree/develop

[kwankyu]

comment:101

Replying to @slel:

The release manager's develop branch is at:

• https://github.com/vbraun/sage/tree/develop

Thanks. I added that to my repo as git remote with name vbraun :)

[kwankyu]

comment:102

By the way, it is nice to see the Sage documentation right from the status badge!

[vbraun]

Changed branch from u/klee/33309 to acecf84

[mkoeppe]

Changed commit from acecf84 to none

[mkoeppe]

comment:104

Follow-up = #33529