Have the Sage version number present on every page of the documentation

[Tinkidinki]

Generally, documentation pages are reached by googling, and it would be convenient to have the Sage version number on every page of the documentation.

While this is present on the first page of the references, on the top left corner here: https://doc.sagemath.org/html/en/reference/index.html#discrete-mathematics , it is not present on every other page. For example, a random page that appeared after googling 'sage matrices':
http://doc.sagemath.org/html/en/reference/matrices/sage/matrix/constructor.html

This would especially be convenient when previous version documentation is archived somewhere, to know what version number it corresponds to.

For example, version 9.0 of sage has the following page for "named permutation groups": http://doc.sagemath.org/html/en/reference/groups/sage/groups/perm_gps/permgroup_named.html
while an archived docpage on some other website has this, which has a few differences from the original: https://www.math.sciences.univ-nantes.fr/~sorger/chow/html/en/reference/groups/sage/groups/perm_gps/permgroup_named.html

Now, the archived version seems to be v6.4.1, found after clicking "index" on the top right: https://www.math.sciences.univ-nantes.fr/~sorger/chow/html/en/reference/genindex.html

However, this is not apparent at all while looking at the docs.

So, basically: would like to have the Sage version number on every page of the documentation somewhere.

Component: documentation

Keywords: version website

Author: Mahathi Vempati, John Palmieri

Branch/Commit: 1a64a0f

Reviewer: Markus Wageringel

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

[mwageringel]

comment:1

The version number is actually in the title of the HTML page (possibly hover the tab in your browser to fully see it), but I agree it would be nice if this was more visible.

[jhpalmieri]

comment:2

A patch like this helps, but it could probably be tinkered with:

diff --git a/src/doc/en/reference/conf_sub.py b/src/doc/en/reference/conf_sub.py
index 058fc01101..fdc8556550 100644
--- a/src/doc/en/reference/conf_sub.py
+++ b/src/doc/en/reference/conf_sub.py
@@ -39,14 +39,14 @@ if not title:
 title = title.replace(u'`', u'$')
 
 # General information about the project.
-project = u'Sage Reference Manual: ' + title
+project = u'Sage {} Reference Manual: '.format(release) + title
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-html_title = u'Sage Reference Manual v' + release + ': ' + title
+html_title = project
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
-html_short_title = title
+html_short_title = project
 
 # HTML theme (e.g., 'default', 'sphinxdoc').  The pages for the
 # reference manual use a custom theme, a slight variant on the 'sage'

[Tinkidinki]

comment:3

Replying to @jhpalmieri:

A patch like this helps, but it could probably be tinkered with:

diff --git a/src/doc/en/reference/conf_sub.py b/src/doc/en/reference/conf_sub.py
index 058fc01101..fdc8556550 100644
--- a/src/doc/en/reference/conf_sub.py
+++ b/src/doc/en/reference/conf_sub.py
@@ -39,14 +39,14 @@ if not title:
 title = title.replace(u'`', u'$')
 
 # General information about the project.
-project = u'Sage Reference Manual: ' + title
+project = u'Sage {} Reference Manual: '.format(release) + title
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-html_title = u'Sage Reference Manual v' + release + ': ' + title
+html_title = project
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
-html_short_title = title
+html_short_title = project
 
 # HTML theme (e.g., 'default', 'sphinxdoc').  The pages for the
 # reference manual use a custom theme, a slight variant on the 'sage'

Thank you! This looks good. I'm a little new to this - so can you confirm if this is how it works?

I did a checkout ticket number, and a local branch got created. The code changes that you mention in this comment were not present in it though.

Assuming whatever you wrote in this comment is the way to fix the issue, how does one go about fixing it?

1. Do I just make the changes on my local branch and then push?
2. How can I see how the HTML page will look locally first?
3. What are the steps for it to finally reflect in the actual documentation?

If any of those questions can be answered by just reading a resource, please just point me there.

Thank you very much!

[jhpalmieri]

comment:4

Right, I didn't post a branch, so checking out this ticket doesn't do anything, as you observed. You can make the changes on your local branch (for example, click the "Unified" button on my proposed patch, select the patch, paste to a file, and do git apply FILE). Once you've done that, build the documentation with make. The main documentation will be in local/share/doc/sage/html/en, so you could for example open local/share/doc/sage/html/en/index.html in a browser. You should also check non-English documentation by opening files in local/share/doc/sage/html/[LANGUAGE]/ for appropriate values of [LANGUAGE].

[Tinkidinki]

Branch: t/28962/have_the_sage_version_number_present_on_every_page_of_the_documentation

[Tinkidinki]

comment:5

I get the following error when I try to apply the patch:

error: patch with only garbage at line 3

As an aside, for small changes, is there an advantage to applying a patch over normally editing the file?

[Tinkidinki]

Changed branch from t/28962/have_the_sage_version_number_present_on_every_page_of_the_documentation to none

[Tinkidinki]

Branch: u/Tinkidinki/have_the_sage_version_number_present_on_every_page_of_the_documentation

[Tinkidinki]

Changed branch from u/Tinkidinki/have_the_sage_version_number_present_on_every_page_of_the_documentation to u/gh-Tinkidinki/have_the_sage_version_number_present_on_every_page_of_the_documentation

[sagetrac-git]

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

57aa440	Testing the branch
db4a1cc	Revert "Testing the branch"
081c028	Changed conf_sub.py to include version number in every page of the documentation

[sagetrac-git]

Commit: 081c028

[Tinkidinki]

comment:10

Tested that the code works on random English references pages. Other languages did not seem to have refererences pages - only single page tutorials.

Can anyone review if this is okay?

[mwageringel]

Reviewer: Markus Wageringel

[mwageringel]

comment:11

Thank you. This looks good to me. The documentation files of the other languages already include the version number, so nothing needs to be changed there.

I have squashed your commits. Please add your full name to the Authors field of this ticket.

---

New commits:

d64a31e

Changed conf_sub.py to include version number in every page of the documentation

[mwageringel]

Changed commit from 081c028 to d64a31e

[mwageringel]

Changed branch from u/gh-Tinkidinki/have_the_sage_version_number_present_on_every_page_of_the_documentation to u/gh-mwageringel/28962

[Tinkidinki]

Author: Mahathi Vempati

[mwageringel]

Changed author from Mahathi Vempati to Mahathi Vempati, John Palmieri

[mwageringel]

comment:14

Actually, there is a failing doctest.

[sagetrac-git]

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

1a64a0f

28962: fix doctest in src/sage/docs/conf.py

[sagetrac-git]

Changed commit from d64a31e to 1a64a0f

[mwageringel]

comment:16

Should be fixed now. If the patchbot is green, this can be set back to positive.

[Tinkidinki]

Changed branch from u/gh-mwageringel/28962 to u/gh-Tinkidinki/28962

[vbraun]

Changed branch from u/gh-Tinkidinki/28962 to 1a64a0f