#36672 closed Bug (needsinfo)
Missing certain ToC items when using Dash with Django's docs
| Reported by: | minusf | Owned by: | |
|---|---|---|---|
| Component: | Documentation | Version: | 5.2 |
| Severity: | Normal | Keywords: | sphinx |
| Cc: | Triage Stage: | Unreviewed | |
| Has patch: | no | Needs documentation: | no |
| Needs tests: | no | Patch needs improvement: | no |
| Easy pickings: | no | UI/UX: | no |
Description
While using the offline documentation tool Dash, I have noticed that certain pages are missing certain ToC items while the webpages have no such issues.
I reached out to the author of Dash who has confirmed that the ToC is generated from django's own objects.inv file.
Please see the attached screenshots for Dash's ToC and the websites ToC for the same page "How to create custom template tags and filters".
I am not very familiar with sphinx but I did a make html locally and it seems that is missing certain Header elements from objects.inv:
"Code layout" is present in both:
% grep 'Code layout' uncompressed-objects.inv howto/custom-template-tags:code layout std:label -1 howto/custom-template-tags.html#code-layout Code layout
"Simple tags" is present in both:
% grep 'Simple tags' uncompressed-objects.inv howto-custom-template-tags-simple-tags std:label -1 howto/custom-template-tags.html#$ Simple tags
"Registering custom filters" only in html docs and missing from Dash:
grep 'Registering custom filters' uncompressed-objects.inv
"Registering the tag" only in html and missing from Dash:
grep 'Registering the tag' uncompressed-objects.inv
Attachments (2)
Change History (6)
by , 3 days ago
| Attachment: | django-html-docs.png added |
|---|
by , 3 days ago
| Attachment: | dash-django-docs.png added |
|---|
comment:1 by , 3 days ago
| Resolution: | → needsinfo |
|---|---|
| Status: | new → closed |
| Summary: | Django documentation objects.inv issue → Missing certain ToC items when using Dash with Django's docs |
comment:2 by , 3 days ago
Thank you for your comment.
Obviously this is nothing of high priority. It might be a sphinx issue or a styling issue, or something completely different, I am a coder and don't build big extensive documentations with sphinx like the django docs.
I find Dash useful, and I'd like to read the django documentation in it, and correct ToC's are really nice to have, so I was hoping the maintainers of the documentation might give a quick looksee at this issue and it might be trivial to fix it with the right pair of eyes.
Wouldn't there be some usefulness to keep this ticket a bit longer open so others might find it? If nothing comes off of it, and I can find the time, I might go down that rabbit hole later, but it'd be nice to hear the docs team's opinion...
comment:3 by , 26 hours ago
Django doesn't have a special group of documentation maintainers. I've contributed to the documentation since 2009, and my assessment is that debugging issues with third-party tools isn't the priority of our volunteer contributors.
I did provide a possible cause. If confirmed, I don't know that it's feasible for us to fix it by labeling every ToC heading in the documentation. Perhaps Dash needs to revisit its approach for generating headings.
Does the report refer to Dash for Mac? (A paid app.) I think it's a niche request, but the ticket is here awaiting further details.
comment:4 by , 25 hours ago
Dash is paid but it has a free version that nags. The dash author was nice enough to make all his docsets available to Zeal, which is an open source dash clone. I don't know the size of their user bases and whether it's niche or not.
Thank you for looking into this, I'll see if I can make any progress or not.
I suspect this may have something to do with the fact that these sections aren't labeled (or that they are labeled by
sphinx.ext.autosectionlabel). Perhaps Dash doesn't detect such sections. I don't think it's the job of Django's maintainers to investigate this further, so if you or Dash maintainers want to continue investigating and propose some change to Django (if needed), feel free to reopen with more details.