[New-bugs-announce] [issue45139] Simplify source links in documentation?

[Jean Abou Samra]

New submission from Jean Abou Samra <jean at abou-samra.fr>:

Currently, links to source code in the documentation look like this:

**Source code:** :source:`Lib/abc.py`

For documentation translators, this means that every module contains
a boilerplate string to translate. A small burden perhaps, but avoidable.
I propose to refactor the links in a directive, like so:

.. source:: Lib/abc.py

Then just the text "Source code:" gets translated (in sphinx.po) and
the rest is automatic. This could also benefit the presentation in
the future, if anyone wants to change the styling of these links.

Open question is how to handle the handful of links that contain several
source files (async I/O modules in particular). To make it language-agnostic,
perhaps the markup

.. source::
   Lib/asyncio/futures.py,
   Lib/asyncio/base_futures.py

could be rendered as if it were

**Source code:** :source:`Lib/asyncio/futures.py` | :source:`Lib/asyncio/base_futures.py`

Thoughts?

----------
assignee: docs at python
components: Documentation
messages: 401410
nosy: Jean_Abou_Samra, docs at python, mdk
priority: normal
severity: normal
status: open
title: Simplify source links in documentation?

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue45139>
_______________________________________