Description

bitdancer

opened on Oct 10, 2014

Issue body actions

BPO	22593
Nosy	@bitdancer, @JulienPalard, @isidentical, @nmassman
PRs	gh-66783: Automate update of Unicode data version in documentation #17748

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2014-10-10.01:11:38.378>
labels = ['easy', 'type-feature', '3.9', 'docs']
title = 'Automate update of doc references to UCD version when it changes.'
updated_at = <Date 2019-12-30.07:44:23.371>
user = 'https://github.com/bitdancer'

bugs.python.org fields:

activity = <Date 2019-12-30.07:44:23.371>
actor = 'ned.deily'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2014-10-10.01:11:38.378>
creator = 'r.david.murray'
dependencies = []
files = []
hgrepos = []
issue_num = 22593
keywords = ['patch', 'easy']
message_count = 4.0
messages = ['228935', '356923', '358895', '359017']
nosy_count = 5.0
nosy_names = ['r.david.murray', 'docs@python', 'mdk', 'BTaskaya', 'nmassman']
pr_nums = ['17748']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue22593'
versions = ['Python 3.9']

Activity

1. bitdancer commented on Oct 10, 2014

   

   bitdancer

   on Oct 10, 2014

   MemberAuthor

   More actions

   As noted by Alexander in bpo-18176, we often forget to update the UCD references in the docs when we switch to a new version. That issue added notes to the makeunicodedata script to list the places that need to be changed; however, it would be even better if makeunicodedata could somehow do the update automatically.

   One possible way to do this easily might be to leverage sphinx 'substitutions' (I couldn't make that work in a short experiment, so it might not be feasible). If not, it should be simple enough to write something to automate the editing of the lines in the rst files (probably using a hardcoded list of locations, but possibly by grepping for the URL pattern).

   Alexander also discussed the possibility of auto-generating tables to insert into the documentation, in the context of the PropList.txt file. I don't know if this is practical or desirable.
2. bitdancer

   added

   easy

   type-featureA feature request or enhancementA feature request or enhancement

   on Oct 10, 2014
3. isidentical commented on Nov 18, 2019

   

   isidentical

   on Nov 18, 2019

   SponsorMember

   More actions

   I want to work on this. What do you think about using include directive and include a static file like UCD_VERSION.txt in the documents?

   makeunicodedata.py can write the current version every run to UCD_VERSION.txt
4. nmassman commented on Dec 27, 2019

   

   nmassmanmannequin

   on Dec 27, 2019

   Mannequin

   More actions

   I took a crack at the rst side of this, to see if I could reduce it to just one easy to parse for line in each file that needs to be modified.

   Yeah, not so easy.

   Substituting text in rst isn't hard, you just insert '|ucd_version|' where the version string should go and then include the following line somewhere below.

   .. |ucd_version| replace:: 12.1.0

   The problem is that I cant find any combination that makes this work for substituting the version string inside of a hyperlink. I've tried multiple combinations and every time the hyperlink gets broken.

   So this, inside Doc/library/stdtypes.rst:

   See http://www.unicode.org/Public/\\ |ucd_version|\ /ucd/extracted/DerivedNumericType.txt

   Becomes this in the html:

   See <a class="reference external" href="http://www.unicode.org/Public/"\>http://www.unicode.org/Public/\</a>12.1.0/ucd/extracted/DerivedNumericType.txt

   It does in fact do the substitution, but the substituted text onward doesn't get included in the hyperlink.

   It gets worse if you try to hyperlink text instead of just the url.

   In Doc/library/unicodedata.rst I tried this:

   compiled from the |ucd_link|_.

   .. |ucd_link| replace:: UCD version |ucd_version|
   .. _ucd_link: http://www.unicode.org/Public/|ucd_version|/ucd

   and got:

   compiled from the <a class="reference external" href="http://www.unicode.org/Public/|ucd_version|/ucd"\>UCD version 12.1.0</a>

   The sub inside a sub works fine, but no combination I tried could get it to work in the hyperlink itself.

   Near as I can tell, the only way to accomplish this would require adding or possibly creating a plugin for sphinx.
5. nmassman commented on Dec 30, 2019

   

   nmassmanmannequin

   on Dec 30, 2019

   Mannequin

   More actions

   I ended up doing exactly what I said would probably be needed, and wrote a small sphinx extension that handles this. I kept the same reST substitution syntax, but I'm parsing for '|ucd_version|' as the source files are read in and just replacing it with the version number.

   Feedback is much appreciated. This is my first really involved PR. :)
6. ned-deily

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   3.9 (EOL)end of lifeend of life

   on Dec 30, 2019
7. ned-deily

   assigned

   docspython

   on Dec 30, 2019
8. ezio-melotti

   transferred this issue fromon Apr 10, 2022
9. AA-Turner commented on Jan 12, 2024

   

   AA-Turner

   on Jan 12, 2024

   Member

   More actions

   We've managed thus far without such an extension -- having reviewed the PR I think this doesn't meet the bar for complexity/benefit.

   A
10. AA-Turner

    closed this as not plannedon Jan 12, 2024

Issue actions