[Django] #28290: Doc sections are missing target (labels) links
Django
-------------------------------------+-------------------------------------
Reporter: Tony | Owner: nobody
Narlock |
Type: | Status: new
Cleanup/optimization |
Component: | Version: 1.11
Documentation | Keywords: docs labels
Severity: Normal | intersphinx
Triage Stage: | Has patch: 0
Unreviewed |
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 1
UI/UX: 0 |
-------------------------------------+-------------------------------------
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
([https://github.com/django/django/blob/01f6586/docs/topics/http/sessions.txt#L172
git], [https://docs.djangoproject.com/en/1.11/topics/http/sessions/#using-
sessions-in-views docs])
Shell ([https://github.com/django/django/blob/a30482a/docs/ref/django-
admin.txt#L971 git] [https://docs.djangoproject.com/en/1.11/ref/django-
admin/#shell docs])
--
Ticket URL: <https://code.djangoproject.com/ticket/28290>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
-------------------------------------+-------------------------------------
Type: | Narlock
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 1.11
Severity: Normal | Resolution:
Keywords: docs labels | Triage Stage:
intersphinx | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* status: new => assigned
* owner: nobody => Tony Narlock
Comment:
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 siera.
--
Ticket URL: <https://code.djangoproject.com/ticket/28290#comment:1>
Django
-------------------------------------+-------------------------------------
Type: | Narlock
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 1.11
Severity: Normal | Resolution:
intersphinx |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* stage: Unreviewed => Accepted
--
Ticket URL: <https://code.djangoproject.com/ticket/28290#comment:2>
Django
-------------------------------------+-------------------------------------
Type: | Narlock
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 1.11
Severity: Normal | Resolution:
Keywords: docs labels | Triage Stage: Accepted
intersphinx |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by 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
--
Ticket URL: <https://code.djangoproject.com/ticket/28290#comment:3>
Django
-------------------------------------+-------------------------------------
Type: | Narlock
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 1.11
Severity: Normal | Resolution:
Keywords: docs labels | Triage Stage: Accepted
intersphinx |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by 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
--
Ticket URL: <https://code.djangoproject.com/ticket/28290#comment:4>
Django
-------------------------------------+-------------------------------------
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 1.11
Severity: Normal | Resolution:
Keywords: docs labels | Triage Stage: Accepted
intersphinx |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* owner: Tony Narlock => (none)
* status: assigned => new
Comment:
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!
--
Ticket URL: <https://code.djangoproject.com/ticket/28290#comment:5>
Django
-------------------------------------+-------------------------------------
Type: | kamalesh0406
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 1.11
Severity: Normal | Resolution:
Keywords: docs labels | Triage Stage: Accepted
intersphinx |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* owner: (none) => kamalesh0406
* status: new => assigned
--
Ticket URL: <https://code.djangoproject.com/ticket/28290#comment:6>
Django
-------------------------------------+-------------------------------------
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 1.11
Severity: Normal | Resolution:
Keywords: docs labels | Triage Stage: Accepted
intersphinx |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* owner: Kamalesh Palanisamy => Kees Hink
Comment:
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()`).
--
Ticket URL: <https://code.djangoproject.com/ticket/28290#comment:7>
Django
-------------------------------------+-------------------------------------
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 1.11
Severity: Normal | Resolution:
Keywords: docs labels | Triage Stage: Accepted
intersphinx |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by tapaswenipathak):
Hello folks: Can I take the ticket?
--
Ticket URL: <https://code.djangoproject.com/ticket/28290#comment:8>
Django
-------------------------------------+-------------------------------------
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 1.11
Severity: Normal | Resolution:
Keywords: docs labels | Triage Stage: Accepted
intersphinx |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* owner: Kees Hink => Abhijeet
* has_patch: 0 => 1
Comment:
My patch: https://github.com/django/django/pull/12251
Discussion: https://groups.google.com/forum/#!topic/django-developers
/sRfq48rD-Ao
--
Ticket URL: <https://code.djangoproject.com/ticket/28290#comment:9>
Django
-------------------------------------+-------------------------------------
Cleanup/optimization |
Component: Documentation | Version: 1.11
Keywords: docs labels | Triage Stage: Accepted
intersphinx |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"1a9459b88e4b07b3f4dd80ed5987e13111afe1c2" 1a9459b]:
{{{
#!CommitTicketReference repository=""
revision="1a9459b88e4b07b3f4dd80ed5987e13111afe1c2"
Fixed #28290 -- Enabled Sphinx auto-label generation for title and section
headers.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/28290#comment:10>