most cross-references in sphinx-generated HTML are wrong

[niccl]

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

[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.

[Alex Gaynor]

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

[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.

[Ramiro Morales]

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.