Opened 7 months ago

Last modified 7 months ago

#28290 assigned Cleanup/optimization

Doc sections are missing target (labels) links

Reported by: Tony Narlock Owned by: Tony Narlock
Component: Documentation Version: 1.11
Severity: Normal Keywords: docs labels intersphinx
Cc: Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

Experiencing this while writing an article about Django. Some sections are missing intersphinx references.

This has actually been plaguing me for a few years when trying to link up Django's excellent docs via sphinx. Probably 85% of intersphinx links to Django work perfectly, but there are some outliers.

With sphinx installed (pip install --user sphinx), this command can be used to print intersphinx reference names to stdout (for double checking).

python -m sphinx.ext.intersphinx 'http://docs.djangoproject.com/en/1.11/_objects/'

Supposedly, docutils/sphinx is supposed to automatically assign target links:

Labels that aren’t placed before a section title can still be referenced to, but you must give the link an explicit title, using this syntax: :ref:Link title <label-name>.

source: http://www.sphinx-doc.org/en/stable/markup/inline.html#role-ref

For reference, I also opened a possibly related Sphinx-doc ticket about that: https://github.com/sphinx-doc/sphinx/issues/3856

Here are a few cases of missing sections that need manual labels:

Using Sessions in views (git, docs)

Shell (git docs)

Change History (4)

comment:1 Changed 7 months ago by Tony Narlock

Owner: changed from nobody to Tony Narlock
Status: newassigned

Here is another one I can't get a header for.

https://docs.djangoproject.com/en/1.11/topics/http/views/#a-simple-view

https://github.com/django/django/blob/424187e/docs/topics/http/views.txt#L15

To add, using sphinx 1.6.3, python 3.6.1, macOS sierra.

Last edited 7 months ago by Tony Narlock (previous) (diff)

comment:2 Changed 7 months ago by Tim Graham

Triage Stage: UnreviewedAccepted
Note: See TracTickets for help on using tickets.
Back to Top