Doc sections are missing target (labels) links

[Tony Narlock]

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)

[Tony Narlock]

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.

[Tony Narlock]

Another find, in the Middleware section, probably spans across other sections i the document too:

​https://github.com/django/django/blob/e27e4c0/docs/topics/http/middleware.txt#L98

​https://docs.djangoproject.com/en/1.11/topics/http/middleware/#activating-middleware

and

​https://github.com/django/django/blob/01f6586/docs/topics/http/sessions.txt#L172

​https://docs.djangoproject.com/en/1.11/topics/http/sessions/#using-sessions-in-views

[Tony Narlock]

​http://www.sphinx-doc.org/en/stable/ext/autosectionlabel.html

This could be of assistance.

See ​https://github.com/sphinx-doc/sphinx/issues/3856

[Carlton Gibson]

Hi Tony, I'm going to deassign this. It's been 20months without a patch, and as an Easy Pickings ticket it's likely to get picked up quickly if not claimed. Please do reclaim if you do in fact have a patch. Thanks for the report!

[Kees Hink]

To make sure i understand the issue correctly: What is missing is the link to the source code. There's a working example of such a [source] link in ​https://docs.djangoproject.com/en/2.2/howto/custom-management-commands/#django.core.management.BaseCommand. That link takes you to ​https://docs.djangoproject.com/en/2.2/_modules/django/core/management/base/#BaseCommand. I think this is also the intended behavior for the reported pages, because there's a class directive.

When i follow the instruction to add a header below the class directive, i get these errors:

/Users/kees/Projects/django/docs/topics/http/sessions.txt:434: WARNING: py:meth reference target not found: backends.base.SessionBase.flush
/Users/kees/Projects/django/docs/topics/http/sessions.txt:443: WARNING: py:meth reference target not found: backends.base.SessionBase.set_test_cookie
/Users/kees/Projects/django/docs/topics/http/sessions.txt:443: WARNING: py:meth reference target not found: backends.base.SessionBase.test_cookie_worked
/Users/kees/Projects/django/docs/topics/http/sessions.txt:454: WARNING: py:meth reference target not found: backends.base.SessionBase.delete_test_cookie
/Users/kees/Projects/django/docs/topics/http/sessions.txt:585: WARNING: py:meth reference target not found: backends.base.SessionBase.set_expiry
/Users/kees/Projects/django/docs/topics/http/sessions.txt:694: WARNING: py:meth reference target not found: backends.base.SessionBase.clear_expired

So probably this is the right direction, but sphinx can't find all methods in the code. Why, i have no idea. There are no errors for the other referenced methods from backends.base.SessionBase (like get_expiry_date()).

[Tapasweni Pathak]

Hello folks: Can I take the ticket?

[Abhijeet Viswa]

My patch: ​https://github.com/django/django/pull/12251
Discussion: ​https://groups.google.com/forum/#!topic/django-developers/sRfq48rD-Ao

[GitHub <noreply@…>]

In 1a9459b:

Fixed #28290 -- Enabled Sphinx auto-label generation for title and section headers.