#28962 closed enhancement (fixed)

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

Reported by: gh-Tinkidinki Owned by:
Priority: minor Milestone: sage-9.1
Component: documentation Keywords: version website
Cc: Merged in:
Authors: Mahathi Vempati, John Palmieri Reviewers: Markus Wageringel
Report Upstream: N/A Work issues:
Branch: 1a64a0f (Commits, GitHub, GitLab) Commit: 1a64a0f132dc93eb235bf8e53c2b7d8be335ba16
Dependencies: Stopgaps:

Status badges

Description

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.

Change History (19)

comment:1 Changed 21 months ago by gh-mwageringel

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.

comment:2 follow-up: Changed 21 months ago by jhpalmieri

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

  • src/doc/en/reference/conf_sub.py

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

comment:3 in reply to: ↑ 2 Changed 21 months ago by gh-Tinkidinki

Replying to jhpalmieri:

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

  • src/doc/en/reference/conf_sub.py

    diff --git a/src/doc/en/reference/conf_sub.py b/src/doc/en/reference/conf_sub.py
    index 058fc01101..fdc8556550 100644
    a b if not title: 
    3939title = title.replace(u'`', u'$')
    4040
    4141# General information about the project.
    42 project = u'Sage Reference Manual: ' + title
     42project = u'Sage {} Reference Manual: '.format(release) + title
    4343
    4444# The name for this set of Sphinx documents.  If None, it defaults to
    4545# "<project> v<release> documentation".
    46 html_title = u'Sage Reference Manual v' + release + ': ' + title
     46html_title = project
    4747
    4848# A shorter title for the navigation bar.  Default is the same as html_title.
    49 html_short_title = title
     49html_short_title = project
    5050
    5151# HTML theme (e.g., 'default', 'sphinxdoc').  The pages for the
    5252# 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!

comment:4 Changed 21 months ago by jhpalmieri

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].

comment:5 Changed 21 months ago by gh-Tinkidinki

  • Branch set to t/28962/have_the_sage_version_number_present_on_every_page_of_the_documentation

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?

comment:6 Changed 21 months ago by gh-Tinkidinki

  • Branch t/28962/have_the_sage_version_number_present_on_every_page_of_the_documentation deleted

comment:7 Changed 21 months ago by gh-Tinkidinki

  • Branch set to u/Tinkidinki/have_the_sage_version_number_present_on_every_page_of_the_documentation

comment:8 Changed 21 months ago by gh-Tinkidinki

  • Branch changed 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

comment:9 Changed 21 months ago by git

  • Commit set to 081c028a1457788d6b5d2f3d135b42f698603516

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

57aa440Testing the branch
db4a1ccRevert "Testing the branch"
081c028Changed conf_sub.py to include version number in every page of the documentation

comment:10 Changed 21 months ago by gh-Tinkidinki

  • Status changed from new to needs_review

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?

comment:11 Changed 20 months ago by gh-mwageringel

  • Branch changed from u/gh-Tinkidinki/have_the_sage_version_number_present_on_every_page_of_the_documentation to u/gh-mwageringel/28962
  • Commit changed from 081c028a1457788d6b5d2f3d135b42f698603516 to d64a31efc3ddf0f20a05c40cd9a09e5af3323430
  • Reviewers set to Markus Wageringel

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:

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

comment:12 Changed 20 months ago by gh-Tinkidinki

  • Authors set to Mahathi Vempati

comment:13 Changed 20 months ago by gh-mwageringel

  • Authors changed from Mahathi Vempati to Mahathi Vempati, John Palmieri
  • Status changed from needs_review to positive_review

comment:14 Changed 20 months ago by gh-mwageringel

  • Status changed from positive_review to needs_work

Actually, there is a failing doctest.

comment:15 Changed 20 months ago by git

  • Commit changed from d64a31efc3ddf0f20a05c40cd9a09e5af3323430 to 1a64a0f132dc93eb235bf8e53c2b7d8be335ba16

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

1a64a0f28962: fix doctest in src/sage/docs/conf.py

comment:16 Changed 20 months ago by gh-mwageringel

  • Status changed from needs_work to needs_review

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

comment:17 Changed 20 months ago by gh-Tinkidinki

  • Branch changed from u/gh-mwageringel/28962 to u/gh-Tinkidinki/28962

comment:18 Changed 20 months ago by gh-mwageringel

  • Status changed from needs_review to positive_review

comment:19 Changed 19 months ago by vbraun

  • Branch changed from u/gh-Tinkidinki/28962 to 1a64a0f132dc93eb235bf8e53c2b7d8be335ba16
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.