classification
Title: Use |version| instead of X.Y in the doc
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: chris.jerdonek, docs@python, eric.araujo, ezio.melotti, georg.brandl, mikehoy, python-dev, serhiy.storchaka, sponster, terry.reedy
Priority: normal Keywords: easy, patch

Created on 2011-03-22 23:55 by eric.araujo, last changed 2016-05-07 14:25 by serhiy.storchaka. This issue is now closed.

Files
File name Uploaded Description Edit
issue11643-xy_v1.diff mikehoy, 2012-10-06 08:48 X.Y, {X.Y},|version| review
Messages (10)
msg131816 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-03-22 23:55
Some files like site.rst use “X.Y” to refer to the Python version, but Sphinx helpfully provides a |version| construct that can be replaced by the current version at build time.
msg132376 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-03-27 22:26
If the docs literally use "X.Y", so that that can be grepped, then attaching a grep result would make this even easier for someone on Windows without grep.
msg132378 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-03-27 22:49
Yes, this was literal.  grep result on 3.1:

c-api/intro.rst:73:path and then use ``#include <pythonX.Y/Python.h>``; this will break on
c-api/intro.rst:534:directory named :file:`lib/python{X.Y}` relative to the parent directory
c-api/intro.rst:540::file:`/usr/local/lib/python{X.Y}`.  (In fact, this particular path is also
faq/general.rst:356:titled "Python X.Y Release Schedule", where X.Y is a version that hasn't been
howto/urllib2.rst:156:``Python-urllib/x.y`` (where ``x`` and ``y`` are the major and minor version
install/index.rst:240:| Unix (pure)     | :file:`{prefix}/lib/python{X.Y}/site-packages`      | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1)  |
install/index.rst:242:| Unix (non-pure) | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1)  |
install/index.rst:265:Windows, choose :menuselection:`Start --> Programs --> Python X.Y -->
install/index.rst:386:| pure module distribution     | :file:`{prefix}/lib/python{X.Y}/site-packages`      | :option:`--install-purelib` |
install/index.rst:388:| non-pure module distribution | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :option:`--install-platlib` |
install/index.rst:634:the search path will be set to ``['', '/www/python/lib/pythonX.Y/',
install/index.rst:635:'/www/python/lib/pythonX.Y/plat-linux2', ...]``.
library/site.rst:42::file:`/usr/local`.  The Python X.Y library is then installed in
library/site.rst:43::file:`/usr/local/lib/python{X.Y}` (where only the first three characters of
library/site.rst:45:a subdirectory :file:`/usr/local/lib/python{X.Y}/site-packages` with three
library/site.rst:65:   /usr/local/lib/pythonX.Y/site-packages/bar
library/site.rst:66:   /usr/local/lib/pythonX.Y/site-packages/foo
library/pydoc.rst:67:``http://docs.python.org/X.Y/library/`` where ``X`` and ``Y`` are the
library/logging.rst:442:found for logger X.Y.Z" is printed to the console. This message is intended
library/logging.rst:464:done using loggers with names matching "foo.x.y", then the code::
library/stdtypes.rst:2324:'/usr/local/lib/pythonX.Y/os.pyc'>``.

There are also things like “python2.3”:
extending/building.rst:97:   gcc -DNDEBUG -g -O3 -Wall -Wstrict-prototypes -fPIC -DMAJOR_VERSION=1 -DMINOR_VERSION=0 -I/usr/local/include -I/usr/local/include/python2.2 -c demo.c -o build/temp.linux-i686-2.2/demo.o
faq/extending.rst:240::file:`/usr/lib/python2.{x}/config/` directory, which contains various files
faq/general.rst:500:   python2.2 <pathto>/db2pickley.py database.db database.pck
install/index.rst:362:them to go in :file:`/usr/local/lib/python2.{X}` rather than
install/index.rst:363::file:`/usr/lib/python2.{X}`.  This can be done with ::
install/index.rst:370:modules in :file:`/usr/local/lib/python2.{X}`, but those modules would have to
install/index.rst:371:be installed to, say, :file:`/mnt/{@server}/export/lib/python2.{X}`.  This could
install/index.rst:590:   ['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',
install/index.rst:591:    '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',
install/index.rst:592:    '/usr/local/lib/python2.3/site-packages']
install/index.rst:703:   :file:`{prefix}/lib/python1.5/site-packages/distutils`, so the system
library/sysconfig.rst:243:            platlib = "/usr/local/lib/python3.2/site-packages"
library/sysconfig.rst:244:            platstdlib = "/usr/local/lib/python3.2"
library/sysconfig.rst:245:            purelib = "/usr/local/lib/python3.2/site-packages"
library/sysconfig.rst:247:            stdlib = "/usr/local/lib/python3.2"
library/re.rst:1115:     File "/usr/local/lib/python3.2/re.py", line 132, in match
tutorial/interpreter.rst:13:The Python interpreter is usually installed as :file:`/usr/local/bin/python3.2`
tutorial/interpreter.rst:17:   python3.2
tutorial/interpreter.rst:97:   $ python3.2
tutorial/interpreter.rst:151:   #! /usr/bin/env python3.2

(Please ignore distutils and install docs, they’re frozen except for bugfixes, there’s no value in working on them with the replacement coming Really Soon Now™.)

Do docs people agree this automation would be something useful?

FYI: https://pypi.python.org/pypi/grin/1.2.1
msg136267 - (view) Author: Tom McDermott (sponster) Date: 2011-05-19 04:02
Things are slightly worse than this issue suggests: the Sphinx formatting string |version| has leaked into the html docs in a few places (library/site.html for example).

The difficulty is that Sphinx isn't expanding the |version| variable inside :file: markup.
msg170585 - (view) Author: Mike Hoy (mikehoy) * Date: 2012-09-17 06:21
So we could fix this in reverse? Remove the |version| and replace them with X.Y since |version| doesn't expand within :file:?
msg170589 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-09-17 07:01
New changeset de6976fe19aa by Ezio Melotti in branch '2.7':
#11643: fix rst markup error in site.rst.
http://hg.python.org/cpython/rev/de6976fe19aa

New changeset 7aca2781c381 by Ezio Melotti in branch '3.2':
#11643: fix rst markup error in site.rst.
http://hg.python.org/cpython/rev/7aca2781c381

New changeset c6892ce7e56f by Ezio Melotti in branch 'default':
#11643: merge with 3.2.
http://hg.python.org/cpython/rev/c6892ce7e56f
msg170590 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-09-17 07:03
I fixed the one in site.py.
If there's no way to use |version| in :file:`...` I think using {X.Y} is OK, so that can be done where a bare X.Y (without {}) is currently used.
msg172173 - (view) Author: Mike Hoy (mikehoy) * Date: 2012-10-06 08:48
Here is a patch after talking with Ezio on irc tonight. The rules I (attempted) to follow are:

Within a :file: you should have {X.Y}
In a text/paragraph area you can use |version|
Within anything else just leave it as X.Y

As stated by Éric I ignored install and distutils.
msg172209 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-10-06 15:23
After reviewing the patch I think that this change would not actually improve things.  What do you think?  (Thanks for the patch nonetheless :)*
msg265072 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2016-05-07 14:25
Agree with Éric.
History
Date User Action Args
2016-05-07 14:25:20serhiy.storchakasetstatus: open -> closed

nosy: + serhiy.storchaka
messages: + msg265072

resolution: rejected
stage: needs patch -> resolved
2012-10-06 15:23:14eric.araujosetmessages: + msg172209
2012-10-06 08:48:49mikehoysetfiles: + issue11643-xy_v1.diff
keywords: + patch
2012-10-06 08:48:14mikehoysetmessages: + msg172173
2012-09-17 07:03:51ezio.melottisetmessages: + msg170590
2012-09-17 07:01:12python-devsetnosy: + python-dev
messages: + msg170589
2012-09-17 06:21:39mikehoysetmessages: + msg170585
2012-09-17 06:12:02mikehoysetnosy: + mikehoy
2012-08-09 15:25:54chris.jerdoneksetnosy: + chris.jerdonek
2012-08-09 13:31:53ezio.melottisettype: enhancement
versions: + Python 3.4, - Python 3.1
2011-05-20 15:03:57eric.araujosetnosy: + georg.brandl
2011-05-19 04:02:38sponstersetnosy: + sponster
messages: + msg136267
2011-03-27 22:49:37eric.araujosetmessages: + msg132378
2011-03-27 22:26:47terry.reedysetnosy: + terry.reedy
messages: + msg132376
2011-03-23 00:10:20ezio.melottisetnosy: + ezio.melotti
2011-03-22 23:55:11eric.araujocreate