Changeset 599

Timestamp:

17/04/09 11:12:18 (17 months ago)

Author:

athomas

Message:

Doc cleanup.

Location:

cly/trunk/doc

Files:

• Makefile (modified) (1 diff)
• api/builder.rst (modified) (1 diff)
• conf.py (modified) (7 diffs)
• index.rst (modified) (1 diff)
• makedocs.py (deleted)
• stylesheet.css (deleted)
• tutorial.rst (modified) (2 diffs)
• video1.py (deleted)

cly/trunk/doc/Makefile

@@ -10 +10 @@
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d .build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html web pickle htmlhelp latex changes linkcheck
+.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
 
 help:
         @echo "Please use \`make <target>' where <target> is one of"
         @echo "  html      to make standalone HTML files"
-        @echo "  pickle    to make pickle files (usable by e.g. sphinx-web)"
+        @echo "  dirhtml   to make HTML files named index.html in directories"
+        @echo "  pickle    to make pickle files"
+        @echo "  json      to make JSON files"
         @echo "  htmlhelp  to make HTML files and a HTML help project"
+        @echo "  qthelp    to make HTML files and a qthelp 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 "  changes   to make an overview of all changed/added/deprecated items"
         @echo "  linkcheck to check all external links for integrity"
+        @echo "  doctest   to run all doctests embedded in the documentation (if enabled)"
 
 clean:
-        -rm -rf .build/*
+        -rm -rf _build/*
 
 html:
-        mkdir -p .build/html .build/doctrees
-        $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) .build/html
+        $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html
         @echo
-        @echo "Build finished. The HTML pages are in .build/html."
+        @echo "Build finished. The HTML pages are in _build/html."
+
+dirhtml:
+        $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) _build/dirhtml
+        @echo
+        @echo "Build finished. The HTML pages are in _build/dirhtml."
 
 pickle:
-        mkdir -p .build/pickle .build/doctrees
-        $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) .build/pickle
+        $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
         @echo
-        @echo "Build finished; now you can process the pickle files or run"
-        @echo "  sphinx-web .build/pickle"
-        @echo "to start the sphinx-web server."
+        @echo "Build finished; now you can process the pickle files."
 
-web: pickle
+json:
+        $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) _build/json
+        @echo
+        @echo "Build finished; now you can process the JSON files."
 
 htmlhelp:
-        mkdir -p .build/htmlhelp .build/doctrees
-        $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) .build/htmlhelp
+        $(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."
+              ".hhp project file in _build/htmlhelp."
+
+qthelp:
+        $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) _build/qthelp
+        @echo
+        @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+              ".qhcp project file in _build/qthelp, like this:"
+        @echo "# qcollectiongenerator _build/qthelp/CLY.qhcp"
+        @echo "To view the help file:"
+        @echo "# assistant -collectionFile _build/qthelp/CLY.qhc"
 
 latex:
-        mkdir -p .build/latex .build/doctrees
-        $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) .build/latex
+        $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
         @echo
-        @echo "Build finished; the LaTeX files are in .build/latex."
+        @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
+        $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes
         @echo
-        @echo "The overview file is in .build/changes."
+        @echo "The overview file is in _build/changes."
 
 linkcheck:
-        mkdir -p .build/linkcheck .build/doctrees
-        $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) .build/linkcheck
+        $(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."
+              "or in _build/linkcheck/output.txt."
+
+doctest:
+        $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) _build/doctest
+        @echo "Testing of doctests in the sources finished, look at the " \
+              "results in _build/doctest/output.txt."

cly/trunk/doc/api/builder.rst

@@ -4 +4 @@
 .. automodule:: cly.builder
    :members:
+   :noindex:

cly/trunk/doc/conf.py

@@ -2 +2 @@
 #
 # CLY documentation build configuration file, created by
-# sphinx-quickstart on Tue Jun 10 18:04:10 2008.
+# sphinx-quickstart on Fri Apr 17 04:34:12 2009.
 #
 # 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).
+# Note that not all possible configuration values are present in this
+# autogenerated file.
 #
-# All configuration values have a default value; values that are commented out
-# serve to show the default value.
+# All configuration values have a default; values that are commented out
+# serve to show the default.
 
 import sys, os
 
-# If your extensions are in another directory, add it here. If the directory
-# is relative to the documentation root, use os.path.abspath to make it
-# absolute, like shown here.
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.append(os.path.abspath('..'))
 
-# General configuration
-# ---------------------
+# -- 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 = ['sphinx.ext.autodoc']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest']
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['.templates']
+templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = '.rst'
 
+# The encoding of source files.
+#source_encoding = 'utf-8'
+
 # The master toctree document.
 master_doc = 'index'
 
-# General substitutions.
-project = 'CLY'
-copyright = '2008, Alec Thomas'
+# General information about the project.
+project = u'CLY'
+copyright = u'2009, Alec Thomas'
 
-# The default replacements for |version| and |release|, also used in various
-# other places throughout the built documents.
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
 #
 # The short X.Y version.
@@ -47 +50 @@
 release = '1.0'
 
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
 # 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'
+#today_fmt = '%B %d, %Y'
 
 # List of documents that shouldn't be included in the build.
 #unused_docs = []
 
-# List of directories, relative to source directories, that shouldn't be searched
+# List of directories, relative to source directory, that shouldn't be searched
 # for source files.
-#exclude_dirs = []
+exclude_trees = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
@@ -72 +82 @@
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'trac'
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
 
 
-# Options for HTML output
-# -----------------------
+# -- 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'
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+html_theme = 'basic'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
 
 # The name for this set of Sphinx documents.  If None, it defaults to
@@ -87 +106 @@
 #html_title = None
 
-# The name of an image file (within the static path) to place at the top of
-# the sidebar.
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
 #html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
 
 # 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 = ['static']
+html_static_path = ['_static']
 
 # 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'
+#html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
@@ -114 +141 @@
 #html_use_modindex = True
 
-# If true, the reST sources are included in the HTML build as _sources/<name>.
-#html_copy_source = True
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
 
 # If true, an OpenSearch description file will be output, and all pages will
@@ -129 +162 @@
 
 
-# Options for LaTeX output
-# ------------------------
+# -- Options for LaTeX output --------------------------------------------------
 
 # The paper size ('letter' or 'a4').
@@ -139 +171 @@
 
 # Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, document class [howto/manual]).
+# (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'CLY.tex', 'CLY Documentation', 'Alec Thomas', 'manual'),
+  ('index', 'CLY.tex', u'CLY Documentation',
+   u'Alec Thomas', 'manual'),
 ]
 

cly/trunk/doc/index.rst

@@ -1 @@
-.. CLY documentation master file, created by sphinx-quickstart on Tue Jun 10 18:04:10 2008.
+.. CLY documentation master file, created by
+   sphinx-quickstart on Fri Apr 17 04:34:12 2009.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to CLY
-==============
+Welcome to CLY's documentation!
+===============================
 
 

cly/trunk/doc/tutorial.rst

@@ -24 +24 @@
 .. code-block:: python
    
-    grammar = XMLGrammar(...)
+    grammar = XMLGrammar('grammar.xml', ...)
 
 with the corresponding:
@@ -30 +30 @@
 .. code-block:: python
    
-    grammar = Grammar(...)
+    grammar = Grammar(grammar, ...)