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 with a working implementation is proposed below.

NOTE THAT CSS COPYRIGHT ISSUES NEED TO BE SOLVED BEFORE THIS CAN BE MERGED. The CSS is Copyright (c) 2005 Lawrence Journal-World. Perhaps it can be shared at least with a Creative Commons Attribution-Noncommercial-No Derivative Works 3.0 United States License?

My patch is of course entirely in public domain.

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 [DONE]
  • 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) [DONE]
  • using the customized docutils classes from source:djangoproject.com/django_website/apps/docs/builder.py [DONE]
• the inter-page links should be converted to make them work properly (by extending the docutils classes) [DONE]
• less important: external images from ​http://media.djangoproject.com/img/doc/ can be retrieved and image links converted accordingly (--with-images option perhaps?)

Implementation

The proposal has been implemented, inter-page links and table of contents work. Images have not been dealt with, I doubt if they are worth the trouble. CSS images are another thing though, but they are trivial to add, only copyright issues need to be sorted out.

Usage:

$ trunk/django/bin/django-admin.py help htmldocs
Usage: django-admin.py htmldocs [options] [Django documentation directory] [output directory]

Converts Django documentation to HTML. Uses the given Django documentation directory for reading
documentation source and output directory for writing HTML files. Creates the output directory if it does not exist.

Options:
  --settings=SETTINGS   The Python path to a settings module, e.g.
                        "myproject.settings.main". If this isn't provided, the
                        DJANGO_SETTINGS_MODULE environment variable will be
                        used.
  --pythonpath=PYTHONPATH
                        A directory to add to the Python path, e.g.
                        "/home/djangoprojects/myproject".
  --traceback           Print traceback on exception
  --single              Write a single combined HTML file. Not recommended,
                        produces output that is harder to navigate.
  --version             show program's version number and exit
  -h, --help            show this help message and exit

This is an example run:

$ trunk/django/bin/django-admin.py htmldocs trunk/docs foo
Writing 'foo/add_ons.html'...  done
Writing 'foo/admin_css.html'...  done
Writing 'foo/apache_auth.html'...  done
Writing 'foo/api_stability.html'...  done
Writing 'foo/authentication.html'...  done
Writing 'foo/cache.html'...  done
Writing 'foo/contenttypes.html'...  done
Writing 'foo/contributing.html'...  done
Writing 'foo/csrf.html'...  done
Writing 'foo/custom_model_fields.html'...  done
Writing 'foo/databases.html'...  done
Writing 'foo/databrowse.html'...  done
Writing 'foo/db-api.html'...  done
Writing 'foo/design_philosophies.html'...  done
Writing 'foo/distributions.html'...  done
Writing 'foo/django-admin.html'...  done
Writing 'foo/documentation.html'...  done
Writing 'foo/email.html'...  done
Writing 'foo/faq.html'...  done
Writing 'foo/fastcgi.html'...  done
Writing 'foo/flatpages.html'...  done
Writing 'foo/form_for_model.html'...  done
Writing 'foo/form_preview.html'...  done
Writing 'foo/form_wizard.html'...  done
Writing 'foo/forms.html'...  done
Writing 'foo/generic_views.html'...  done
Writing 'foo/i18n.html'...  done
Writing 'foo/install.html'...  done
Writing 'foo/legacy_databases.html'...  done
Writing 'foo/localflavor.html'...  done
Writing 'foo/middleware.html'...  done
Writing 'foo/model-api.html'...  done
Writing 'foo/modelforms.html'...  done
Writing 'foo/modpython.html'...  done
Writing 'foo/newforms.html'...  done
Writing 'foo/outputting_csv.html'...  done
Writing 'foo/outputting_pdf.html'...  done
Writing 'foo/overview.html'...  done
Writing 'foo/pagination.html'...  done
Writing 'foo/redirects.html'...  done
Writing 'foo/release_notes_0.95.html'...  done
Writing 'foo/release_notes_0.96.html'...  done
Writing 'foo/request_response.html'...  done
Writing 'foo/serialization.html'...  done
Writing 'foo/sessions.html'...  done
Writing 'foo/settings.html'...  done
Writing 'foo/shortcuts.html'...  done
Writing 'foo/sitemaps.html'...  done
Writing 'foo/sites.html'...  done
Writing 'foo/static_files.html'...  done
Writing 'foo/syndication_feeds.html'...  done
Writing 'foo/templates.html'...  done
Writing 'foo/templates_python.html'...  done
Writing 'foo/testing.html'...  done
Writing 'foo/transactions.html'...  done
Writing 'foo/tutorial01.html'...  done
Writing 'foo/tutorial02.html'...  done
Writing 'foo/tutorial03.html'...  done
Writing 'foo/tutorial04.html'...  done
Writing 'foo/unicode.html'...  done
Writing 'foo/url_dispatch.html'...  done
Writing 'foo/webdesign.html'...  done
Writing index...  done
All done

A page from multi-page output looks like this:

The single-page output looks like this:

The patch against [7321] is attached in attachment:build_htmldocs.diff