:ref:`section title` should work w/o explicit label

Ben Franksen avatarBen Franksen created an issue

Currently I have to write:

.. _Built-in Functions:

Built-in Functions

if I want to refer to the section from other documents using :ref:.

I think this is redundant and also goes against the spirit of documentation being human readable even as plain text.

Comments (2)

  1. Georg Brandl

    The label doesn't have to have the same text as the heading: you could use .. _builtins: for example.

    This is by design: so that you don't need to change lots of links when changing the heading (or translating it).

  2. Ben Franksen

    Well, it is your decision, of course, but I suggest you re-think your rationale.

    First, the feature I requested would not prevent you from using a separate label if that is the way you like to work.

    Second, I do not plan to ever translate the documentation for my project. I just do not have the manpower for that, and since I often work to improve it, any translation would be out of date very soon. I think this situation is not untypical, there are lots of one-man projects out there.

    Last not least, chosing a different text for the label actually makes things more difficult for me. Each time I want to add a cross-reference, I have to look up the name of the label. I find it a lot easier to remember the section name. Besides, I usually have a web-browser open where I can read the formatted version of what I write, and I can find section headings there easily via the local TOC. The label I have to look up in the rst sources.

    Having to add a separate label makes it harder for people to add cross-references. This is bad since in my experience, the more cross-references, the easier it is to navigate around a complex project, especially if you are still unfamiliar with it. Therefore adding a cross-reference should be as easy as possible for the documentation writer.

  3. Log in to comment
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.