Changes between Version 13 and Version 14 of DjangoSpecifications/Docs/ConvertingRestToOtherFormats


Ignore:
Timestamp:
Mar 9, 2010, 6:47:26 PM (15 years ago)
Author:
James Bennett
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • DjangoSpecifications/Docs/ConvertingRestToOtherFormats

    v13 v14  
    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 with a working implementation is proposed below.
    8 
    9 '''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?
    10 
    11 My patch is of course entirely in public domain.
    12 
    13 == Proposal ==
    14 
    15 Generating offline documentation should work as follows:
    16  * there is a command '''builddocs''' that can be called from either `django-admin.py` or `manage.py`
    17   * that produces multiple-page HTML output from the docs by default, but accepts the option `--single` to produce single-page output [DONE]
    18   * 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)
    19  * the converter tries to make the documentation look similar to web docs by
    20    * using (a subset of) the Django official CSS http://media.djangoproject.com/css/homepage.css (discuss copyright issues) [DONE]
    21    * using the customized docutils classes from source:djangoproject.com/django_website/apps/docs/builder.py [DONE]
    22  * the inter-page links should be converted to make them work properly (by extending the docutils classes) [DONE]
    23  * less important: external images from http://media.djangoproject.com/img/doc/ can be retrieved and image links converted accordingly (`--with-images` option perhaps?)
    24 
    25 == Implementation ==
    26 
    27 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.
    28 
    29 The final patch against [7321] is attached in attachment:build_htmldocs-links_work-with_docs.diff
    30 
    31 Usage:
    32 {{{
    33 $ trunk/django/bin/django-admin.py help htmldocs
    34 Usage: django-admin.py htmldocs [options] [Django documentation directory] [output directory]
    35 
    36 Converts Django documentation to HTML. Uses the given Django documentation directory for reading
    37 documentation source and output directory for writing HTML files. Creates the output directory if it does not exist.
    38 
    39 Options:
    40   --settings=SETTINGS   The Python path to a settings module, e.g.
    41                         "myproject.settings.main". If this isn't provided, the
    42                         DJANGO_SETTINGS_MODULE environment variable will be
    43                         used.
    44   --pythonpath=PYTHONPATH
    45                         A directory to add to the Python path, e.g.
    46                         "/home/djangoprojects/myproject".
    47   --traceback           Print traceback on exception
    48   --single              Write a single combined HTML file. Not recommended,
    49                         produces output that is harder to navigate.
    50   --version             show program's version number and exit
    51   -h, --help            show this help message and exit
    52 }}}
    53 
    54 This is an example run:
    55 {{{
    56 $ trunk/django/bin/django-admin.py htmldocs trunk/docs foo
    57 Writing 'foo/add_ons.html'...  done
    58 Writing 'foo/admin_css.html'...  done
    59 Writing 'foo/apache_auth.html'...  done
    60 Writing 'foo/api_stability.html'...  done
    61 Writing 'foo/authentication.html'...  done
    62 Writing 'foo/cache.html'...  done
    63 Writing 'foo/contenttypes.html'...  done
    64 Writing 'foo/contributing.html'...  done
    65 Writing 'foo/csrf.html'...  done
    66 Writing 'foo/custom_model_fields.html'...  done
    67 Writing 'foo/databases.html'...  done
    68 Writing 'foo/databrowse.html'...  done
    69 Writing 'foo/db-api.html'...  done
    70 Writing 'foo/design_philosophies.html'...  done
    71 Writing 'foo/distributions.html'...  done
    72 Writing 'foo/django-admin.html'...  done
    73 Writing 'foo/documentation.html'...  done
    74 Writing 'foo/email.html'...  done
    75 Writing 'foo/faq.html'...  done
    76 Writing 'foo/fastcgi.html'...  done
    77 Writing 'foo/flatpages.html'...  done
    78 Writing 'foo/form_for_model.html'...  done
    79 Writing 'foo/form_preview.html'...  done
    80 Writing 'foo/form_wizard.html'...  done
    81 Writing 'foo/forms.html'...  done
    82 Writing 'foo/generic_views.html'...  done
    83 Writing 'foo/i18n.html'...  done
    84 Writing 'foo/install.html'...  done
    85 Writing 'foo/legacy_databases.html'...  done
    86 Writing 'foo/localflavor.html'...  done
    87 Writing 'foo/middleware.html'...  done
    88 Writing 'foo/model-api.html'...  done
    89 Writing 'foo/modelforms.html'...  done
    90 Writing 'foo/modpython.html'...  done
    91 Writing 'foo/newforms.html'...  done
    92 Writing 'foo/outputting_csv.html'...  done
    93 Writing 'foo/outputting_pdf.html'...  done
    94 Writing 'foo/overview.html'...  done
    95 Writing 'foo/pagination.html'...  done
    96 Writing 'foo/redirects.html'...  done
    97 Writing 'foo/release_notes_0.95.html'...  done
    98 Writing 'foo/release_notes_0.96.html'...  done
    99 Writing 'foo/request_response.html'...  done
    100 Writing 'foo/serialization.html'...  done
    101 Writing 'foo/sessions.html'...  done
    102 Writing 'foo/settings.html'...  done
    103 Writing 'foo/shortcuts.html'...  done
    104 Writing 'foo/sitemaps.html'...  done
    105 Writing 'foo/sites.html'...  done
    106 Writing 'foo/static_files.html'...  done
    107 Writing 'foo/syndication_feeds.html'...  done
    108 Writing 'foo/templates.html'...  done
    109 Writing 'foo/templates_python.html'...  done
    110 Writing 'foo/testing.html'...  done
    111 Writing 'foo/transactions.html'...  done
    112 Writing 'foo/tutorial01.html'...  done
    113 Writing 'foo/tutorial02.html'...  done
    114 Writing 'foo/tutorial03.html'...  done
    115 Writing 'foo/tutorial04.html'...  done
    116 Writing 'foo/unicode.html'...  done
    117 Writing 'foo/url_dispatch.html'...  done
    118 Writing 'foo/webdesign.html'...  done
    119 Writing index...  done
    120 All done
    121 }}}
    122 
    123 A page from multi-page output looks like this:
    124 
    125 [[Image(Screenshot.png)]]
    126 
    127 The single-page output looks like this:
    128 
    129 [[Image(Screenshot_single.png)]]
     1This page and several others were created by a wiki user who was not and is not affiliated with the Django project. Previous contents of this and other similar pages are not and should not be confused with [http://docs.djangoproject.com/ Django's own documentation], which remains the sole source of official documentation for the Django project.
Back to Top