Add links to sources in documentation

[kwankyu]

• Add a top banner to the sage doc of the stable version if the present doc is for a develop version.
• Add small edit button (using a furo feature) to github source files for rst files.
• Add [source] links to github source files in the reference manual (using sphinx linkcode extension).
• Edited src/sage/misc/sageinspect.py
• Deprecate sage-classic theme (but leave theme files yet).

Fixes #35223.

📝 Checklist

• The title is concise and informative.
• The description explains in detail what this PR is about.
• I have linked a relevant issue or discussion.
• I have created tests covering the changes.
• I have updated the documentation accordingly.

⌛ Dependencies

[mkoeppe]

This is looking great, thanks for working on it!
Ready for review?

[kwankyu]

There are still two problems:

1. Note that the edit buttion of for example,

https://deploy-preview-37589--sagemath.netlify.app/html/en/reference/function_fields/sage/rings/function_field/function_field

opens a different page. This is somewhat disappointing. I could not do better because of #35223 (comment):

... As far as I understand, this is not feasible for our reference manual since the reference manual is generated by autodoc and multi-doc from our source code files, which are distinct from the rst files, from which Sphinx generates the HTML documentation. The edit buttion would direct to the rst files, which are absent in our repo.

I am looking for a workaround, but failing.

2. If you click the [source] button, the corresponding github page opens. We expect that a user can edit the file, and commit, and open a PR from there. in my experiment, I failed to open a PR because github does not know where to make a branch for it. A branch should be made in my forked repo, but github attempts to make one to sagemath/sage. GIthub does not ask where to make the branch... Perhaps I am doing something wrong. Any idea?

[mkoeppe]

2. If you click the [source] button, the corresponding github page opens. We expect that a user can edit the file, and commit, and open a PR from there. in my experiment, I failed to open a PR because github does not know where to make a branch for it. A branch should be made in my forked repo, but github attempts to make one to sagemath/sage. GIthub does not ask where to make the branch... Perhaps I am doing something wrong. Any idea?

It sends me to the page for a specific tag, and there a speech bubble informs me that I can't edit it.

I switched to the "develop" branch, then it offers that I can "Edit in place", which leads to an editor with a big green "Commit changes..." button.

I didn't go through with, out of perhaps excessive caution.

Instead I edited the URL to go to my fork instead.
Editing it there and pushing the big green "Commit changes..." button sends me to this dialog:

I assume that it will likewise present meaningful options when users without write privileges in sagemath/sage push "Edit in place" in the sagemath/sage repository.

[kwankyu]

It sends me to the page for a specific tag, and there a speech bubble informs me that I can't edit it. ... I switched to the "develop" branch, then it offers that I can "Edit in place", which leads to an editor with a big green "Commit changes..." button.

The url is created with the version of the doc. This may be changed. We can use "develop" instead. But using the version of the doc seems right.

I didn't go through with, out of perhaps excessive caution.

I ventured to go through. Github failed me saying that I don't have the right.

I assume that it will likewise present meaningful options when users without write privileges in sagemath/sage push "Edit in place" in the sagemath/sage repository.

Perhaps. But not sure...

[mkoeppe]

The url is created with the version of the doc. This may be changed. We can use "develop" instead. But using the version of the doc seems right.

I would suggest using "develop" instead to streamline the process for potential contributors. Yes, there may be a surprise for them that they see a newer version -- but this could even be a pleasant surprise when what they are trying to fix is already fixed. Better than having them prepare an edited version based on an old version, and then preparing a PR, and then rebasing, ....

[kwankyu]

I fixed the Problem 1.

Regarding the Problem 2, we just provide links to the source files, it is up to the user how to proceed to edit the file on github.

I fixed the version to the develop branch. Yes, this is convenient for most cases.

How about the banner?

[mkoeppe]

How about the banner?

Looks fine to me. Ideally, for documentation built from PRs it would give a link to the PR instead of saying that it's for the development version. But that can be a follow-up.

[mkoeppe]

I assume the failing docbuild is unrelated. I've seen such failures recently elsewhere.

[kwankyu]

... Ideally, for documentation built from PRs it would give a link to the PR instead of saying that it's for the development version.

I am not sure that having the doc's behavior dependent on the git branch is a good idea, if I understand you correctly...

[github-actions]

Documentation preview for this PR (built with commit 918ff5c; changes) is ready! 🎉

[kwankyu]

I assume the failing docbuild is unrelated. I've seen such failures recently elsewhere.

I fixed some genuine failures. Now good to go. Thanks for the review.

[mkoeppe]

Looking great. Thanks.

[tornaria]

On 10.4.beta1:

Doctesting 1 file.
sage -t --random-seed=17576084731749778285520792701997981837 src/sage/misc/sageinspect.py
**********************************************************************
File "src/sage/misc/sageinspect.py", line 45, in sage.misc.sageinspect
Failed example:
    sage_getdoc(BlockFinder).lstrip()[:50]
Expected:
    'Provide a "tokeneater()" method to detect the end '
Got:
    'Provide a :meth:tokeneater method to detect the en'
**********************************************************************
1 item had failures:
   1 of  27 in sage.misc.sageinspect
    [353 tests, 1 failure, 18.93 s]
----------------------------------------------------------------------
sage -t --random-seed=17576084731749778285520792701997981837 src/sage/misc/sageinspect.py  # 1 doctest failed
----------------------------------------------------------------------

[kwankyu]

Strange. There's no failure for me:

sage -t --warn-long 69.5 --random-seed=17576084731749778285520792701997981837 src/sage/misc/sageinspect.py
    [353 tests, 14.19 s]
----------------------------------------------------------------------
All tests passed!
----------------------------------------------------------------------

$ sage
┌────────────────────────────────────────────────────────────────────┐
│ SageMath version 10.4.beta1, Release Date: 2024-03-31              │
│ Using Python 3.12.2. Type "help()" for help.                       │
└────────────────────────────────────────────────────────────────────┘
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Warning: this is a prerelease version, and it may be unstable.     ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
sage: from sage.misc.sageinspect import *
sage: sage_getdoc(BlockFinder).lstrip()[:50]
'Provide a "tokeneater()" method to detect the end '

This is right because sage_getdoc returns the formatted docstring.

[tornaria]

Indeed, the doctest example is wrong here:

┌────────────────────────────────────────────────────────────────────┐
│ SageMath version 10.4.beta1, Release Date: 2024-03-31              │
│ Using Python 3.12.2. Type "help()" for help.                       │
└────────────────────────────────────────────────────────────────────┘
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Warning: this is a prerelease version, and it may be unstable.     ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
sage: from sage.misc.sageinspect import sage_getdoc, BlockFinder
sage: sage_getdoc(BlockFinder)
"    Provide a :meth:tokeneater method to detect the end of a code block.\n\n    This is the Python library's :class:inspect.BlockFinder modified\n    to recognize Cython definitions.\n    \n"
sage: 

But this looks almost what the source contains (except the source contains some backticks that are removed):

...
class BlockFinder:
    """  
    Provide a :meth:`tokeneater` method to detect the end of a code block.

    This is the Python library's :class:`inspect.BlockFinder` modified
    to recognize Cython definitions.
    """
    def __init__(self):
...

[kwankyu]

The question is why sage_getdoc(BlockFinder) returns a seeming broken string on your system. Compare with

https://mybinder.org/v2/gh/sagemath/sage-binder-env/dev

where I get

too

[mkoeppe]

@tornaria Could this be because you have patched out the runtime use of Sphinx?

[tornaria]

@tornaria Could this be because you have patched out the runtime use of Sphinx?

No, I did not patch out anything. It's possible that I don't have sphinx installed in that box. Maybe the example can be tagged needs sphinx or else be replaced by a different one that won't require sphinx?

[mkoeppe]

I'll rephrase. As you know, the Sage library declares Sphinx as a runtime dependency ("install-requires"). If you don't install it, then there can be a change of behavior.

[mkoeppe]

Relevant modularization info: src/sage/misc/sagedoc.py is shipped as part of sagemath-objects.
Neither sagemath-objects nor sagemath-repl (which is home of sage.doctest) declare that dependency on Sphinx.

So from the modularization perspective, there may also be a need to do something about this doctest.

[mkoeppe]

So using # needs sphinx should be a fine solution.

However, questions:

• Is this a new failure in the installation without Sphinx?
• Do we have / do we want code that removes such sphinx roles when Sphinx is not present (and thus sage.misc.sphinxify cannot be imported)?

[tornaria]

I'll rephrase. As you know, the Sage library declares Sphinx as a runtime dependency ("install-requires"). If you don't install it, then there can be a change of behavior.

Do you expect me to submit a PR removing Sphinx from "install-requires"?

[mkoeppe]

Maybe explain what you mean by "expect".

[tornaria]

This :meth: role is new and the reason why this didn't fail before and fails now. Note that the :class: role is also not translated, however it's past the first 50 characters that are tested.

[mkoeppe]

So using # needs sphinx should be a fine solution.

Done now as part of:

• pkgs/sagemath-repl/pyproject.toml.m4: Declare extra 'sphinx' #37720 (needs review)