From 7dd4be581beadd8d0ec751054e0f72ef36aef5cf Mon Sep 17 00:00:00 2001 From: Jacob Kaplan-Moss Date: Thu, 27 Mar 2008 15:03:52 +0000 Subject: [PATCH] Added the basics needed to build Django's docs using [http://sphinx.pocoo.org/ Sphinx]. If you've got Sphinx installed (the latest version) along with [http://docutils.sf.net docutils], you should be able to easily build the docs locally using {{{sphinx-build}}} or the included {{{Makefile}}}. This use a basic (and pretty crappy) index for the documentation and the built-in Sphinx styles (which are actually quite nice). git-svn-id: http://code.djangoproject.com/svn/django/trunk@7370 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/Makefile | 68 +++++++++++++++++++++++++ docs/conf.py | 132 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.txt | 128 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 328 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/index.txt diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000000..f79d4299d5 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,68 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = + +# Internal variables. +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 + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " web to make files usable by 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" + @echo " linkcheck to check all external links for integrity" + +clean: + -rm -rf _build/* + +html: + mkdir -p _build/html _build/doctrees + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/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 + @echo + @echo "Build finished; now you can run" + @echo " python -m sphinx.web _build/web" + @echo "to start the server." + +htmlhelp: + mkdir -p _build/htmlhelp _build/doctrees + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in _build/htmlhelp." + +latex: + mkdir -p _build/latex _build/doctrees + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex + @echo + @echo "Build finished; the LaTeX files are in _build/latex." + @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ + "run these through (pdf)latex." + +changes: + mkdir -p _build/changes _build/doctrees + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes + @echo + @echo "The overview file is in _build/changes." + +linkcheck: + mkdir -p _build/linkcheck _build/doctrees + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in _build/linkcheck/output.txt." diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000000..ce313a5cd3 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,132 @@ +# -*- coding: utf-8 -*- +# +# Django documentation build configuration file, created by +# sphinx-quickstart on Thu Mar 27 09:06:53 2008. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# The contents of this file are pickled, so don't put values in the namespace +# that aren't pickleable (module imports are okay, they're removed automatically). +# +# All configuration values have a default value; values that are commented out +# serve to show the default value. + +import sys + +# If your extensions are in another directory, add it here. +#sys.path.append('some/directory') + +# General configuration +# --------------------- + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +#extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = [] + +# The suffix of source filenames. +source_suffix = '.txt' + +# The master toctree document. +master_doc = 'index' + +# General substitutions. +project = 'Django' +copyright = '2008, Django Software Foundation' + +# The default replacements for |version| and |release|, also used in various +# other places throughout the built documents. +# +# The short X.Y version. +version = '$LastChangedRevision$'.split()[1] +# The full version, including alpha/beta/rc tags. +release = version + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +today_fmt = '%B %d, %Y' + +# List of documents that shouldn't be included in the build. +#unused_docs = [] + +# If true, '()' will be appended to :func: etc. cross-reference text. +add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +add_module_names = False + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + + +# Options for HTML output +# ----------------------- + +# The style sheet to use for HTML and HTML Help pages. A file of that name +# must exist either in Sphinx' static/ path, or in one of the custom paths +# given in html_static_path. +html_style = 'default.css' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +html_use_smartypants = True + +# Content template for the index page. +#html_index = '' + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_use_modindex = True + +# If true, the reST sources are included in the HTML build as _sources/. +html_copy_source = True + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Djangodoc' + + +# Options for LaTeX output +# ------------------------ + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, document class [howto/manual]). +#latex_documents = [] + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_use_modindex = True diff --git a/docs/index.txt b/docs/index.txt new file mode 100644 index 0000000000..385ada455c --- /dev/null +++ b/docs/index.txt @@ -0,0 +1,128 @@ +==================== +Django Documentation +==================== + +The essential documentation +=========================== + +If you're new to Django, make sure to read the following documentation in +order.. The rest (in the "reference" section below) can be ready in any order as +you need various functionality. + +.. toctree:: + :maxdepth: 1 + + overview + install + tutorial01 + tutorial02 + tutorial03 + tutorial04 + faq + documentation + +Reference +========= + +.. toctree:: + :maxdepth: 1 + + django-admin + model-api + db-api + transactions + templates + templates_python + newforms + modelforms + testing + sessions + cache + settings + url_dispatch + request_response + generic_views + authentication + shortcuts + unicode + pagination + serialization + i18n + middleware + custom_model_fields + databases + +``django.contrib`` add-ons +-------------------------- + +.. toctree:: + :maxdepth: 1 + + add_ons + contenttypes + csrf + databrowse + flatpages + form_preview + form_wizard + localflavor + redirects + sites + sitemaps + syndication_feeds + webdesign + +Deployment +---------- + +.. toctree:: + :maxdepth: 1 + + modpython + fastcgi + +Solving specific problems +------------------------- + +.. toctree:: + :maxdepth: 1 + + apache_auth + static_files + email + legacy_databases + outputting_pdf + outputting_csv + +Et cetera +--------- + +.. toctree:: + :maxdepth: 1 + + design_philosophies + contributing + admin_css + api_stability + +Release notes +------------- + +.. toctree:: + :maxdepth: 1 + + release_notes_0.96 + release_notes_0.95 + +Also see the list of `backwards-incompatible changes`__ for changes made between +releases. + +__ http://code.djangoproject.com/wiki/BackwardsIncompatibleChanges + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` +