id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
25527	Some formatting issues in the offline PDF documentation (1.8.5 - potentially also other versions)	tuda_vlsi_rt_dsp	nobody	"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"	Cleanup/optimization	closed	Documentation	1.8	Normal	duplicate	Documentation, code example formatting		Unreviewed	1	0	0	0	0	0