| Version 4 (modified by , 17 years ago) ( diff ) |
|---|
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.pyormanage.py- that produces multiple-page HTML output from the docs by default, but accepts the option
--singleto 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)
- that produces multiple-page HTML output from the docs by default, but accepts the option
- 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-imagesoption perhaps?)
Implementation
The proposal has been mostly implemented, though neither inter-page links nor images have been dealt with.
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:
Note:
See TracWiki
for help on using the wiki.