| | 1 | ''Part of DjangoSpecifications'' |
| | 2 | |
| | 3 | = Producing HTML and PDF output from `docs` source = |
| | 4 | |
| | 5 | This is useful for both offline documentation '''and''' reading branch documentation that is usually not available on the web. |
| | 6 | |
| | 7 | #528 is a long-standing ticket that has a basic implementation. A better (perhaps?) approach is proposed below. |
| | 8 | |
| | 9 | == Proposal == |
| | 10 | |
| | 11 | Generating offline documentation should work as follows: |
| | 12 | * there is a command '''builddocs''' that can be called from either `django-admin.py` or `manage.py` |
| | 13 | * that produces multiple-page HTML output from the docs by default, but accepts the option `--single` to produce single-page output |
| | 14 | * 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) |
| | 15 | * the converter tries to make the documentation look similar to web docs by |
| | 16 | * using (a subset of) the Django official CSS http://media.djangoproject.com/css/homepage.css (discuss copyright issues) |
| | 17 | * using the customized docutils classes from source:djangoproject.com/django_website/apps/docs/builder.py |
| | 18 | * the inter-page links should be converted to make them work properly (by extending the docutils classes) |
| | 19 | * less important: external images from http://media.djangoproject.com/img/doc/ can be retrieved and image links converted accordingly (`--with-images` option perhaps?) |