Some formatting issues in the offline PDF documentation (1.8.5 - potentially also other versions)

[tuda_vlsi_rt_dsp]

Code examples in the "official" offline PDF documentation ( ​http://media.readthedocs.org/pdf/django/1.8.x/django.pdf ; available via the ​https://docs.djangoproject.com/en/1.8/ site) appear not very readable (no appropriate formatting as "code box" insert) - first example see Sec. 2.1.1, p. 7 of the PDF, (mysite/news/models.py), many more code inserts in subsequent sections. This seems to be caused by inappropriate handling of "snippet:" tag in the documentation ".txt" source files by Sphinx.

Additional issue with inappropriate handling of

":ref:`Using cached sessions <cached-sessions-backend>`"

in docs/topics/performance.txt (line 277, leads to pdflatex compilation warnings and to the text "462paragraph*.1047" on page ii - between rows

3.21Performance and optimization ..... 458

and

3.22 Serializing Django objects ...465

) --> replacing :ref: by :class: and adapting the length of the subsequent ".." line would resolve that issue, e.g. (<new, >old):

diff topics/performance.txt topics/performance.txt_orig
278,279c278,279
< :class:`Using cached sessions <cached-sessions-backend>`
< ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
---
> :ref:`Using cached sessions <cached-sessions-backend>`
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Suggested workaround / fix on an extracted Django source code archive for the "snippet:" issue:

find ./Django-1.8.5/docs -name "*.txt" -print -exec sed -e 's#.. snippet::#.. code-block::#' \
 -e 's#code-block::$#code-block:: python#' -e 's#:filename:#:caption:#' -ibak {} \;

cd ./Django-1.8.5/docs
make latexpdf

Perhaps a Sphinx documentation guru might check / adapt that approach (e.g. to prevent unwanted side effects on offline HTML or ePUB document creation) and include the updates to the Django documentation sources if appropriate. (Unfortunately, I am just at the beginning of working with the Sphinx documentation tool, but the described procedure helped me to get a readable / printable PDF from the Django 1.8.x docs sources).

Thanks & best regards
Peter

[Tim Graham]

Duplicate of #23751

[Tim Graham <timograham@…>]

In 25f287f6:

Refs #25527 -- Removed redundant doc heading link that leads to a warning when generating PDF.

[Tim Graham <timograham@…>]

In ae225050:

[1.8.x] Refs #25527 -- Removed redundant doc heading link that leads to a warning when generating PDF.

Backport of 25f287f6b2f677213605364c33bb37f33feac953 from master

[Tim Graham <timograham@…>]

In 2c11002f:

[1.9.x] Refs #25527 -- Removed redundant doc heading link that leads to a warning when generating PDF.

Backport of 25f287f6b2f677213605364c33bb37f33feac953 from master