Docs code listings in PDF format are broken

[Graham Wideman]

Affects PDF docs downloaded today, 2015-11-11, from ​https://readthedocs.org/projects/django/downloads/pdf/1.8.x/ (and all other version numbers)

1. Broken rendering of certain code blocks

Throughout the Django docs PDF format, in every code listing that has a grey-bar file name header, the code is formatted unreadably, and appears before the code box, instead of within it.

I will attempt to attach a screenshot. However, examples are easy to find. In the 1.8 PDF this problem can be found starting at page 9, and continuing especially throughout chapter 2 and intermittently elsewhere.

The problem is almost certainly in the apparatus that translates the doc source code into PDF, but is possibly sensitive to the particular combination of nested blocks and formatting of those blocks.

2. Code example text colors print unreadably from the PDF. The font colors for much of the syntax highlighting is too light to print readably on a monochrome printer, even using maximum Acrobat accessibility tricks. This should be a matter of simply darkening the CSS or whatever is used to define syntax colors for the PDF translation.

Since the PDF is the main way to read large chunks for the Django docs in a coherent way, these obstacles make for a significant impediment to would-be learners.

The ePub version is not affected by the code formatting problem, but that format is not a serious solution due to lack of page layout suited for printing and lack of page numbers and section numbers by which to navigate in the 1500+ pages equivalent.

[Graham Wideman]

Sample of broken code formatting in PDF of docs

[Tim Graham]

Duplicate of #23751