Part of DjangoSpecifications

Producing HTML and PDF output from docs source

This is useful for both offline documentation and reading branch documentation that is usually not available on the web.

#528 is a long-standing ticket that has a basic implementation. A better (perhaps?) approach is proposed below.

Proposal

Generating offline documentation should work as follows:

• there is a command builddocs that can be called from either django-admin.py or manage.py
  • that produces multiple-page HTML output from the docs by default, but accepts the option --single to produce single-page output
  • PDF generation is less important, but should be implemented eventually, see ​http://code.google.com/p/rst2pdf (rather than pisa from ​http://www.htmltopdf.org/ as proposed in #528/#6443)
• the converter tries to make the documentation look similar to web docs by
  • using (a subset of) the Django official CSS ​http://media.djangoproject.com/css/homepage.css (discuss copyright issues)
  • using the customized docutils classes from source:djangoproject.com/django_website/apps/docs/builder.py
• the inter-page links should be converted to make them work properly (by extending the docutils classes)
• less important: external images from ​http://media.djangoproject.com/img/doc/ can be retrieved and image links converted accordingly (--with-images option perhaps?)

Implementation

mrts has a somewhat incomplete implementation that will be attached soon.