#25527: Some formatting issues in the offline PDF documentation (1.8.5 -
potentially also other versions)
-------------------------------------+-------------------------------------
Reporter: tuda_vlsi_rt_dsp | Owner: nobody
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 1.8
Severity: Normal | Keywords: Documentation, code
| example formatting
Triage Stage: Unreviewed | Has patch: 1
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
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
--
Ticket URL: <https://code.djangoproject.com/ticket/25527>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/django-updates/059.8b330594d31c656a4c8fca42a83d392b%40djangoproject.com.
For more options, visit https://groups.google.com/d/optout.
