Code

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


Ignore:
Timestamp:
03/09/10 16:47:26 (4 years ago)
Author:
ubernostrum
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.