''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:

[[Image(Screenshot.png)]]

The single-page output looks like this:

[[Image(Screenshot_single.png)]]

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