Permalink
Browse files

Massive reorganization of the docs. See the new docs online at http:/…

  • Loading branch information...
1 parent b3688e8 commit 97cb07c3a10ff0e584a260a7ee1001614691eb1d @jacobian jacobian committed Aug 23, 2008
Showing with 19,944 additions and 17,090 deletions.
  1. +1 −0 AUTHORS
  2. +10 −8 docs/Makefile
  3. +88 −0 docs/_ext/applyxrefs.py
  4. +146 −0 docs/_ext/djangodocs.py
  5. +171 −0 docs/_ext/literals_to_xrefs.py
  6. +3 −0 docs/_static/default.css
  7. +126 −0 docs/_static/djangodocs.css
  8. BIN docs/_static/docicons-behindscenes.gif
  9. BIN docs/_static/docicons-note.gif
  10. BIN docs/_static/docicons-philosophy.gif
  11. +22 −0 docs/_static/homepage.css
  12. +8 −0 docs/_static/reset-fonts-grids.css
  13. +4 −0 docs/_templates/genindex.html
  14. +87 −0 docs/_templates/layout.html
  15. +3 −0 docs/_templates/modindex.html
  16. +3 −0 docs/_templates/search.html
  17. +0 −119 docs/api_stability.txt
  18. +0 −1,173 docs/authentication.txt
  19. +22 −9 docs/conf.py
  20. +36 −0 docs/contents.txt
  21. +0 −297 docs/contenttypes.txt
  22. +0 −2,421 docs/db-api.txt
  23. +0 −138 docs/documentation.txt
  24. +0 −744 docs/faq.txt
  25. +103 −0 docs/faq/admin.txt
  26. +30 −0 docs/faq/contributing.txt
  27. +256 −0 docs/faq/general.txt
  28. +75 −0 docs/faq/help.txt
  29. +16 −0 docs/faq/index.txt
  30. +108 −0 docs/faq/install.txt
  31. +94 −0 docs/faq/models.txt
  32. +65 −0 docs/faq/usage.txt
  33. +0 −388 docs/files.txt
  34. +0 −95 docs/form_preview.txt
  35. +0 −304 docs/form_wizard.txt
  36. +0 −2,468 docs/forms.txt
  37. +0 −1,273 docs/generic_views.txt
  38. +80 −0 docs/glossary.txt
  39. +15 −9 docs/{apache_auth.txt → howto/apache-auth.txt}
  40. +78 −0 docs/howto/custom-file-storage.txt
  41. +33 −0 docs/howto/custom-management-commands.txt
  42. +196 −174 docs/{custom_model_fields.txt → howto/custom-model-fields.txt}
  43. +78 −664 docs/{templates_python.txt → howto/custom-template-tags.txt}
  44. +49 −34 docs/{ → howto/deployment}/fastcgi.txt
  45. +33 −0 docs/howto/deployment/index.txt
  46. +52 −40 docs/{ → howto/deployment}/modpython.txt
  47. +65 −0 docs/howto/error-reporting.txt
  48. +33 −0 docs/howto/index.txt
  49. +140 −0 docs/howto/initial-data.txt
  50. +67 −0 docs/howto/legacy-databases.txt
  51. +27 −30 docs/{outputting_csv.txt → howto/outputting-csv.txt}
  52. +20 −16 docs/{outputting_pdf.txt → howto/outputting-pdf.txt}
  53. +29 −23 docs/{static_files.txt → howto/static-files.txt}
  54. +143 −115 docs/index.txt
  55. BIN docs/internals/_images/djangotickets.png
  56. +39 −23 docs/{ → internals}/contributing.txt
  57. +204 −0 docs/internals/documentation.txt
  58. +22 −0 docs/internals/index.txt
  59. BIN docs/intro/_images/admin01.png
  60. BIN docs/intro/_images/admin02.png
  61. BIN docs/intro/_images/admin02t.png
  62. BIN docs/intro/_images/admin03.png
  63. BIN docs/intro/_images/admin03t.png
  64. BIN docs/intro/_images/admin04.png
  65. BIN docs/intro/_images/admin04t.png
  66. BIN docs/intro/_images/admin05.png
  67. BIN docs/intro/_images/admin05t.png
  68. BIN docs/intro/_images/admin06.png
  69. BIN docs/intro/_images/admin06t.png
  70. BIN docs/intro/_images/admin07.png
  71. BIN docs/intro/_images/admin08.png
  72. BIN docs/intro/_images/admin08t.png
  73. BIN docs/intro/_images/admin09.png
  74. BIN docs/intro/_images/admin10.png
  75. BIN docs/intro/_images/admin11.png
  76. BIN docs/intro/_images/admin11t.png
  77. BIN docs/intro/_images/admin12.png
  78. BIN docs/intro/_images/admin13.png
  79. BIN docs/intro/_images/admin13t.png
  80. BIN docs/intro/_images/admin14.png
  81. BIN docs/intro/_images/admin14t.png
  82. +38 −0 docs/intro/index.txt
  83. +75 −0 docs/intro/install.txt
  84. +44 −33 docs/{ → intro}/overview.txt
  85. +252 −210 docs/{ → intro}/tutorial01.txt
  86. +86 −90 docs/{ → intro}/tutorial02.txt
  87. +133 −111 docs/{ → intro}/tutorial03.txt
  88. +117 −110 docs/{ → intro}/tutorial04.txt
  89. +235 −0 docs/intro/whatsnext.txt
  90. +0 −69 docs/legacy_databases.txt
  91. +0 −733 docs/localflavor.txt
  92. +1 −2 docs/man/django-admin.1
  93. +0 −288 docs/middleware.txt
  94. +95 −0 docs/misc/api-stability.txt
  95. +37 −4 docs/{design_philosophies.txt → misc/design-philosophies.txt}
  96. +4 −4 docs/{ → misc}/distributions.txt
  97. +14 −0 docs/misc/index.txt
  98. +0 −2,145 docs/model-api.txt
  99. BIN docs/obsolete/_images/formrow.gif
  100. BIN docs/obsolete/_images/module.gif
  101. BIN docs/obsolete/_images/objecttools_01.gif
  102. BIN docs/obsolete/_images/objecttools_02.gif
  103. +23 −8 docs/{admin_css.txt → obsolete/admin-css.txt}
  104. +13 −17 docs/{oldforms.txt → obsolete/forms.txt}
  105. +16 −0 docs/obsolete/index.txt
  106. +48 −0 docs/obsolete/newforms-migration.txt
  107. BIN docs/ref/contrib/_images/flatfiles_admin.png
  108. BIN docs/ref/contrib/_images/users_changelist.png
  109. +23 −32 docs/{ → ref/contrib}/admin.txt
  110. +6 −0 docs/ref/contrib/auth.txt
  111. +347 −0 docs/ref/contrib/contenttypes.txt
  112. +8 −3 docs/{ → ref/contrib}/csrf.txt
  113. +26 −20 docs/{ → ref/contrib}/databrowse.txt
  114. +58 −46 docs/{ → ref/contrib}/flatpages.txt
  115. +110 −0 docs/ref/contrib/formtools/form-preview.txt
  116. +316 −0 docs/ref/contrib/formtools/form-wizard.txt
  117. +12 −0 docs/ref/contrib/formtools/index.txt
  118. +91 −0 docs/ref/contrib/humanize.txt
  119. +43 −121 docs/{add_ons.txt → ref/contrib/index.txt}
  120. +651 −0 docs/ref/contrib/localflavor.txt
  121. +21 −20 docs/{ → ref/contrib}/redirects.txt
  122. +343 −0 docs/ref/contrib/sitemaps.txt
  123. +117 −84 docs/{ → ref/contrib}/sites.txt
  124. +204 −175 docs/{syndication_feeds.txt → ref/contrib/syndication.txt}
  125. +13 −8 docs/{ → ref/contrib}/webdesign.txt
  126. +27 −25 docs/{ → ref}/databases.txt
  127. +99 −126 docs/{ → ref}/django-admin.txt
  128. +117 −0 docs/ref/files/file.txt
  129. +13 −0 docs/ref/files/index.txt
  130. +50 −0 docs/ref/files/storage.txt
  131. +688 −0 docs/ref/forms/api.txt
  132. +751 −0 docs/ref/forms/fields.txt
  133. +14 −0 docs/ref/forms/index.txt
  134. +109 −0 docs/ref/forms/validation.txt
  135. +156 −0 docs/ref/forms/widgets.txt
  136. +1,106 −0 docs/ref/generic-views.txt
  137. +21 −0 docs/ref/index.txt
  138. +200 −0 docs/ref/middleware.txt
  139. +902 −0 docs/ref/models/fields.txt
  140. +15 −0 docs/ref/models/index.txt
  141. +430 −0 docs/ref/models/instances.txt
  142. +175 −0 docs/ref/models/options.txt
  143. +1,060 −0 docs/ref/models/querysets.txt
  144. +77 −0 docs/ref/models/relations.txt
  145. +199 −288 docs/{request_response.txt → ref/request-response.txt}
  146. +231 −372 docs/{ → ref}/settings.txt
  147. +612 −0 docs/ref/templates/api.txt
  148. +181 −596 docs/{templates.txt → ref/templates/builtins.txt}
  149. +20 −0 docs/ref/templates/index.txt
  150. +20 −22 docs/{ → ref}/unicode.txt
  151. +6 −6 docs/{release_notes_0.95.txt → releases/0.95.txt}
  152. +8 −6 docs/{release_notes_0.96.txt → releases/0.96.txt}
  153. +2 −0 docs/{release_notes_1.0_alpha.txt → releases/1.0-alpha-1.txt}
  154. +18 −21 docs/{release_notes_1.0_alpha_2.txt → releases/1.0-alpha-2.txt}
  155. +13 −17 docs/{release_notes_1.0_beta_1.txt → releases/1.0-beta.txt}
  156. +26 −0 docs/releases/index.txt
  157. +0 −334 docs/sitemaps.txt
  158. +1,334 −0 docs/topics/auth.txt
  159. +11 −5 docs/{ → topics}/cache.txt
  160. +17 −0 docs/topics/db/index.txt
  161. +191 −0 docs/topics/db/managers.txt
  162. +746 −0 docs/topics/db/models.txt
  163. +968 −0 docs/topics/db/queries.txt
  164. +35 −0 docs/topics/db/sql.txt
  165. +2 −0 docs/{ → topics/db}/transactions.txt
  166. +36 −39 docs/{ → topics}/email.txt
  167. +146 −0 docs/topics/files.txt
  168. +329 −0 docs/topics/forms/formsets.txt
  169. +260 −0 docs/topics/forms/index.txt
  170. +311 −0 docs/topics/forms/media.txt
  171. +16 −13 docs/{ → topics/forms}/modelforms.txt
  172. BIN docs/topics/http/_images/middleware.png
  173. +14 −17 docs/{upload_handling.txt → topics/http/file-uploads.txt}
  174. +7 −0 docs/topics/http/generic-views.txt
  175. +17 −0 docs/topics/http/index.txt
  176. +169 −0 docs/topics/http/middleware.txt
  177. +6 −6 docs/{ → topics/http}/sessions.txt
  178. +14 −17 docs/{ → topics/http}/shortcuts.txt
  179. +31 −33 docs/{url_dispatch.txt → topics/http/urls.txt}
  180. +186 −0 docs/topics/http/views.txt
  181. +48 −42 docs/{ → topics}/i18n.txt
  182. +25 −0 docs/topics/index.txt
  183. +38 −24 docs/{ → topics}/install.txt
  184. +80 −42 docs/{ → topics}/pagination.txt
  185. +14 −14 docs/{ → topics}/serialization.txt
  186. +253 −0 docs/topics/settings.txt
  187. +644 −0 docs/topics/templates.txt
  188. +150 −127 docs/{ → topics}/testing.txt
View
@@ -67,6 +67,7 @@ answer newbie questions, and generally made Django that much better:
Jiri Barton
Ned Batchelder <http://www.nedbatchelder.com/>
batiste@dosimple.ch
+ Batman
Shannon -jj Behrens <http://jjinux.blogspot.com/>
Esdras Beleza <linux@esdrasbeleza.com>
Chris Bennett <chrisrbennett@yahoo.com>
View
@@ -11,12 +11,12 @@ PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-.PHONY: help clean html web htmlhelp latex changes linkcheck
+.PHONY: help clean html web pickle htmlhelp latex changes linkcheck
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
- @echo " web to make files usable by Sphinx.web"
+ @echo " pickle to make pickle files (usable by e.g. sphinx-web)"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " changes to make an overview over all changed/added/deprecated items"
@@ -31,13 +31,15 @@ html:
@echo
@echo "Build finished. The HTML pages are in _build/html."
-web:
- mkdir -p _build/web _build/doctrees
- $(SPHINXBUILD) -b web $(ALLSPHINXOPTS) _build/web
+pickle:
+ mkdir -p _build/pickle _build/doctrees
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
@echo
- @echo "Build finished; now you can run"
- @echo " python -m sphinx.web _build/web"
- @echo "to start the server."
+ @echo "Build finished; now you can process the pickle files or run"
+ @echo " sphinx-web _build/pickle"
+ @echo "to start the sphinx-web server."
+
+web: pickle
htmlhelp:
mkdir -p _build/htmlhelp _build/doctrees
View
@@ -0,0 +1,88 @@
+"""Adds xref targets to the top of files."""
+
+import sys
+import os
+
+testing = False
+
+DONT_TOUCH = (
+ './index.txt',
+ )
+
+def target_name(fn):
+ if fn.endswith('.txt'):
+ fn = fn[:-4]
+ return '_' + fn.lstrip('./').replace('/', '-')
+
+def process_file(fn, lines):
+ lines.insert(0, '\n')
+ lines.insert(0, '.. %s:\n' % target_name(fn))
+ try:
+ f = open(fn, 'w')
+ except IOError:
+ print("Can't open %s for writing. Not touching it." % fn)
+ return
+ try:
+ f.writelines(lines)
+ except IOError:
+ print("Can't write to %s. Not touching it." % fn)
+ finally:
+ f.close()
+
+def has_target(fn):
+ try:
+ f = open(fn, 'r')
+ except IOError:
+ print("Can't open %s. Not touching it." % fn)
+ return (True, None)
+ readok = True
+ try:
+ lines = f.readlines()
+ except IOError:
+ print("Can't read %s. Not touching it." % fn)
+ readok = False
+ finally:
+ f.close()
+ if not readok:
+ return (True, None)
+
+ #print fn, len(lines)
+ if len(lines) < 1:
+ print("Not touching empty file %s." % fn)
+ return (True, None)
+ if lines[0].startswith('.. _'):
+ return (True, None)
+ return (False, lines)
+
+def main(argv=None):
+ if argv is None:
+ argv = sys.argv
+
+ if len(argv) == 1:
+ argv.extend('.')
+
+ files = []
+ for root in argv[1:]:
+ for (dirpath, dirnames, filenames) in os.walk(root):
+ files.extend([(dirpath, f) for f in filenames])
+ files.sort()
+ files = [os.path.join(p, fn) for p, fn in files if fn.endswith('.txt')]
+ #print files
+
+ for fn in files:
+ if fn in DONT_TOUCH:
+ print("Skipping blacklisted file %s." % fn)
+ continue
+
+ target_found, lines = has_target(fn)
+ if not target_found:
+ if testing:
+ print '%s: %s' % (fn, lines[0]),
+ else:
+ print "Adding xref to %s" % fn
+ process_file(fn, lines)
+ else:
+ print "Skipping %s: already has a xref" % fn
+
+if __name__ == '__main__':
+ sys.exit(main())
View
@@ -0,0 +1,146 @@
+"""
+Sphinx plugins for Django documentation.
+"""
+
+import docutils.nodes
+import docutils.transforms
+import sphinx
+import sphinx.addnodes
+import sphinx.builder
+import sphinx.directives
+import sphinx.environment
+import sphinx.htmlwriter
+
+def setup(app):
+ app.add_crossref_type(
+ directivename = "setting",
+ rolename = "setting",
+ indextemplate = "pair: %s; setting",
+ )
+ app.add_crossref_type(
+ directivename = "templatetag",
+ rolename = "ttag",
+ indextemplate = "pair: %s; template tag"
+ )
+ app.add_crossref_type(
+ directivename = "templatefilter",
+ rolename = "tfilter",
+ indextemplate = "pair: %s; template filter"
+ )
+ app.add_crossref_type(
+ directivename = "fieldlookup",
+ rolename = "lookup",
+ indextemplate = "pair: %s, field lookup type",
+ )
+ app.add_description_unit(
+ directivename = "django-admin",
+ rolename = "djadmin",
+ indextemplate = "pair: %s; django-admin command",
+ parse_node = parse_django_admin_node,
+ )
+ app.add_description_unit(
+ directivename = "django-admin-option",
+ rolename = "djadminopt",
+ indextemplate = "pair: %s; django-admin command-line option",
+ parse_node = lambda env, sig, signode: sphinx.directives.parse_option_desc(signode, sig),
+ )
+ app.add_transform(SuppressBlockquotes)
+
+ # Monkeypatch PickleHTMLBuilder so that it doesn't die in Sphinx 0.4.2
+ if sphinx.__version__ == '0.4.2':
+ monkeypatch_pickle_builder()
+
+class SuppressBlockquotes(docutils.transforms.Transform):
+ """
+ Remove the default blockquotes that encase indented list, tables, etc.
+ """
+ default_priority = 300
+
+ suppress_blockquote_child_nodes = (
+ docutils.nodes.bullet_list,
+ docutils.nodes.enumerated_list,
+ docutils.nodes.definition_list,
+ docutils.nodes.literal_block,
+ docutils.nodes.doctest_block,
+ docutils.nodes.line_block,
+ docutils.nodes.table
+ )
+
+ def apply(self):
+ for node in self.document.traverse(docutils.nodes.block_quote):
+ if len(node.children) == 1 and isinstance(node.children[0], self.suppress_blockquote_child_nodes):
+ node.replace_self(node.children[0])
+
+class DjangoHTMLTranslator(sphinx.htmlwriter.SmartyPantsHTMLTranslator):
+ """
+ Django-specific reST to HTML tweaks.
+ """
+
+ # Don't use border=1, which docutils does by default.
+ def visit_table(self, node):
+ self.body.append(self.starttag(node, 'table', CLASS='docutils'))
+
+ # Give each section a unique ID -- nice for custom CSS hooks
+ # This is different on docutils 0.5 vs. 0.4...
+
+ # The docutils 0.4 override.
+ if hasattr(sphinx.htmlwriter.SmartyPantsHTMLTranslator, 'start_tag_with_title'):
+ def start_tag_with_title(self, node, tagname, **atts):
+ node = {
+ 'classes': node.get('classes', []),
+ 'ids': ['s-%s' % i for i in node.get('ids', [])]
+ }
+ return self.starttag(node, tagname, **atts)
+
+ # The docutils 0.5 override.
+ else:
+ def visit_section(self, node):
+ old_ids = node.get('ids', [])
+ node['ids'] = ['s-' + i for i in old_ids]
+ sphinx.htmlwriter.SmartyPantsHTMLTranslator.visit_section(self, node)
+ node['ids'] = old_ids
+
+def parse_django_admin_node(env, sig, signode):
+ command = sig.split(' ')[0]
+ env._django_curr_admin_command = command
+ title = "django-admin.py %s" % sig
+ signode += sphinx.addnodes.desc_name(title, title)
+ return sig
+
+def monkeypatch_pickle_builder():
+ import shutil
+ from os import path
+ try:
+ import cPickle as pickle
+ except ImportError:
+ import pickle
+ from sphinx.util.console import bold
+
+ def handle_finish(self):
+ # dump the global context
+ outfilename = path.join(self.outdir, 'globalcontext.pickle')
+ f = open(outfilename, 'wb')
+ try:
+ pickle.dump(self.globalcontext, f, 2)
+ finally:
+ f.close()
+
+ self.info(bold('dumping search index...'))
+ self.indexer.prune(self.env.all_docs)
+ f = open(path.join(self.outdir, 'searchindex.pickle'), 'wb')
+ try:
+ self.indexer.dump(f, 'pickle')
+ finally:
+ f.close()
+
+ # copy the environment file from the doctree dir to the output dir
+ # as needed by the web app
+ shutil.copyfile(path.join(self.doctreedir, sphinx.builder.ENV_PICKLE_FILENAME),
+ path.join(self.outdir, sphinx.builder.ENV_PICKLE_FILENAME))
+
+ # touch 'last build' file, used by the web application to determine
+ # when to reload its environment and clear the cache
+ open(path.join(self.outdir, sphinx.builder.LAST_BUILD_FILENAME), 'w').close()
+
+ sphinx.builder.PickleHTMLBuilder.handle_finish = handle_finish
+
Oops, something went wrong.

0 comments on commit 97cb07c

Please sign in to comment.