[issue11643] Use |version| instead of X.Y in the doc
New submission from Éric Araujo <merwok@netwok.org>: 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. ---------- assignee: docs@python components: Documentation keywords: easy messages: 131816 nosy: docs@python, eric.araujo priority: normal severity: normal stage: needs patch status: open title: Use |version| instead of X.Y in the doc versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11643> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11643> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: 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. ---------- nosy: +terry.reedy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11643> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: 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 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11643> _______________________________________
Tom McDermott <sponster@gmail.com> added the comment: 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. ---------- nosy: +sponster _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11643> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- nosy: +georg.brandl _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11643> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- type: -> enhancement versions: +Python 3.4 -Python 3.1 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11643> _______________________________________
Changes by Chris Jerdonek <chris.jerdonek@gmail.com>: ---------- nosy: +cjerdonek _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11643> _______________________________________
Changes by Mike Hoy <mhoy09@gmail.com>: ---------- nosy: +mikehoy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11643> _______________________________________
Mike Hoy added the comment: So we could fix this in reverse? Remove the |version| and replace them with X.Y since |version| doesn't expand within :file:? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11643> _______________________________________
Roundup Robot added the comment: 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 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11643> _______________________________________
Ezio Melotti added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11643> _______________________________________
Mike Hoy added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11643> _______________________________________
Changes by Mike Hoy <mhoy09@gmail.com>: ---------- keywords: +patch Added file: http://bugs.python.org/file27446/issue11643-xy_v1.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11643> _______________________________________
Éric Araujo added the comment: After reviewing the patch I think that this change would not actually improve things. What do you think? (Thanks for the patch nonetheless :)* ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11643> _______________________________________
Serhiy Storchaka added the comment: Agree with Éric. ---------- nosy: +serhiy.storchaka resolution: -> rejected stage: needs patch -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11643> _______________________________________
participants (8)
-
Chris Jerdonek -
Ezio Melotti
-
Mike Hoy
-
Roundup Robot
-
Serhiy Storchaka
-
Terry J. Reedy
-
Tom McDermott
-
Éric Araujo