Opened 7 years ago

Closed 6 years ago

#8179 closed (fixed)

most cross-references in sphinx-generated HTML are wrong

Reported by: niccl Owned by: nobody
Component: Documentation Version: master
Severity: Keywords:
Cc: Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

to reproduce (an example)

  • generate the sphinx html documentation using make html in the django_trunk/docs directory
  • (eg) open _build/html/install.html in a browser. The link 'How to use Django with mod_python' (in the Install Apache and mod_python section) points to a modpython directory in the directory above the original directory, instead of modpython.html at the same level as the original file

The reason is that the references are not in the form suggested by the sphinx documentation (http://sphinx.pocoo.org/markup/inline.html#cross-referencing-syntax).

A quick grep indicates there are about 320 instances of the wrong links across 56 of the .txt files.

I'd be happy to claim this ticket, but it seems like there's be a great option for merge conflicts with that many files. Any suggestions? feel free to contact me at nic \at\ tymar \dot\ com if there's an easy way of avoiding conflicts

Change History (6)

comment:1 Changed 7 years ago by jacob

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted
  • Version 1.0-alpha deleted

comment:2 Changed 7 years ago by jacob

  • Version set to SVN

comment:3 Changed 7 years ago by markb

I'm a noob to django but think this bug is quite important because it effectively renders the local documentation almost useless. Most links just don't work.

Also, I am not sure if this is related but the sphinx built html includes a search facility but the reported links also never work. So again, the search facility is useless.

A (arguably unrelated) issue is that I think the docs/ directory should include a basic README.txt file explaining how to build the local docs and where/how to read them. The docs is the first place a noob goes but with a README.txt he can't even bootstrap himself. The README.txt may just say to type "make" and explain the options are little clearer, e.g. make web "to make files usable by Sphinx.web" but what the heck is Sphinx.web, particularly to a noob? README should also say to where/how to read the docs, e.g. $BROWSER docs/_build/html/index.html. All of this is presently very obscure.

comment:4 Changed 7 years ago by Alex

We are working on a doc-refactor branch that changes django's docs to really take advantage of all that sphinx offers. You can see what it looks like at: http://docs.djangoproject.com/ and if you use git you can grab a checkout at: http://code.djangoproject.com/git/?p=django;a=shortlog;h=refs/heads/docs-refactor

comment:5 Changed 7 years ago by markb

Thanks Alex, docs.djangoproject.com looks good. I much prefer to view the syntax highlighted code that sphinx provides in the docs.

Actually just today I see changeset:8506 from "jacob" which puts those new docs into the current svn so the title problem of this ticket is now addressed. However, I still find the search facility does not work and I think my suggestion above about a "bootstrapping" docs/README.txt is warranted.

comment:6 Changed 6 years ago by ramiro

  • Resolution set to fixed
  • Status changed from new to closed

The bug originally reported by the original reporter has been solved. Feel free to open additional tickets (if your search for any similar existing tickets doesn't bring anything) for the bootstrapping documentation document and the search facility for locally generated copied of the documentation issues.

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