Code


Version 4 (modified by anonymous, 6 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.py or manage.py
  • the converter tries to make the documentation look similar to web docs by
  • 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

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:

No image "Screenshot.png" attached to DjangoSpecifications/Docs/ConvertingRestToOtherFormats

The single-page output looks like this:

No image "Screenshot_single.png" attached to DjangoSpecifications/Docs/ConvertingRestToOtherFormats