[Checkins] SVN: Products.CMFCore/trunk/ Add start at Sphinx docs for CMFCore.
Tres Seaver
tseaver at palladion.com
Thu Apr 29 12:04:17 EDT 2010
Log message for revision 111584:
Add start at Sphinx docs for CMFCore.
Changed:
U Products.CMFCore/trunk/.bzrignore
U Products.CMFCore/trunk/buildout.cfg
A Products.CMFCore/trunk/docs/
A Products.CMFCore/trunk/docs/Makefile
A Products.CMFCore/trunk/docs/_static/
A Products.CMFCore/trunk/docs/_templates/
A Products.CMFCore/trunk/docs/api/
A Products.CMFCore/trunk/docs/api/content.rst
A Products.CMFCore/trunk/docs/api/tools.rst
A Products.CMFCore/trunk/docs/conf.py
A Products.CMFCore/trunk/docs/index.rst
-=-
Modified: Products.CMFCore/trunk/.bzrignore
===================================================================
--- Products.CMFCore/trunk/.bzrignore 2010-04-29 15:55:02 UTC (rev 111583)
+++ Products.CMFCore/trunk/.bzrignore 2010-04-29 16:04:17 UTC (rev 111584)
@@ -5,3 +5,4 @@
*.egg-info
./.installed.cfg
*.egg
+docs/_build
Modified: Products.CMFCore/trunk/buildout.cfg
===================================================================
--- Products.CMFCore/trunk/buildout.cfg 2010-04-29 15:55:02 UTC (rev 111583)
+++ Products.CMFCore/trunk/buildout.cfg 2010-04-29 16:04:17 UTC (rev 111584)
@@ -3,8 +3,7 @@
parts =
test
zopepy
- docs
- docs
+ sphinx
unzip = true
@@ -23,6 +22,10 @@
scripts = zopepy
-[docs]
+[sphinx]
recipe = zc.recipe.egg
-eggs = Sphinx
+eggs =
+ Sphinx
+ repoze.sphinx.autointerface
+ Zope2
+ five.localsitemanager
Added: Products.CMFCore/trunk/docs/Makefile
===================================================================
--- Products.CMFCore/trunk/docs/Makefile (rev 0)
+++ Products.CMFCore/trunk/docs/Makefile 2010-04-29 16:04:17 UTC (rev 111584)
@@ -0,0 +1,89 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = _build
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.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 " 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 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 $(BUILDDIR)/*
+
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+pickle:
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json:
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/CMFCore.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/CMFCore.qhc"
+
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+ "run these through (pdf)latex."
+
+changes:
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
Added: Products.CMFCore/trunk/docs/api/content.rst
===================================================================
--- Products.CMFCore/trunk/docs/api/content.rst (rev 0)
+++ Products.CMFCore/trunk/docs/api/content.rst 2010-04-29 16:04:17 UTC (rev 111584)
@@ -0,0 +1,122 @@
+Content API Reference
+=====================
+
+
+.. _core_content:
+
+Core Content
+------------
+
+This interface defines the contract for any content object within the CMF.
+
+.. autointerface:: Products.CMFCore.interfaces.IDynamicType
+ :members:
+
+
+.. _searchable_content:
+
+Searchable Content
+------------------
+
+These interfaces define the contract for content objects which can be
+searched using the :ref:`catalog_tool`.
+
+.. autointerface:: Products.CMFCore.interfaces.IContentish
+ :members:
+
+.. autointerface:: Products.CMFCore.interfaces.ICatalogAware
+ :members:
+
+
+.. _dublin_core_metadata:
+
+Dublin Core Metadata
+--------------------
+
+These interfaces define the contracts for content objects which provide
+standard Dublin Core metadata. See also :ref:`metadata_tool`.
+
+.. autointerface:: Products.CMFCore.interfaces.IMinimalDublinCore
+ :members:
+
+.. autointerface:: Products.CMFCore.interfaces.IDublinCore
+ :members:
+
+.. autointerface:: Products.CMFCore.interfaces.ICatalogableDublinCore
+ :members:
+
+.. autointerface:: Products.CMFCore.interfaces.IMutableMinimalDublinCore
+ :members:
+
+.. autointerface:: Products.CMFCore.interfaces.IMutableDublinCore
+ :members:
+
+
+.. _discussable_content:
+
+Discussable Content
+-------------------
+
+These interfaces define the contracts / framework for content object whose
+discussion can be managed by the :ref:`discussion_tool`.
+
+.. autointerface:: Products.CMFCore.interfaces.IDiscussionResponse
+ :members:
+
+.. autointerface:: Products.CMFCore.interfaces.IOldstyleDiscussable
+ :members:
+
+.. autointerface:: Products.CMFCore.interfaces.IDiscussable
+ :members:
+
+
+.. _content_workflow:
+
+Content Workflow
+----------------
+
+This interface defines the contract for content objects which can participate
+in the workflow framework provided by the :ref:`workflow_tool`.
+
+.. autointerface:: Products.CMFCore.interfaces.IWorkflowAware
+ :members:
+
+
+.. _content_containers:
+
+Content Containers
+-------------------
+
+This interface defines the contract for content objects which can contain
+other content as "normal" sub-items.
+
+.. autointerface:: Products.CMFCore.interfaces.IFolderish
+ :members:
+
+
+Opaque Items
+------------
+
+These interfaces define the framework for content objects which can contain
+other content as "opaque" sub-items.
+
+.. autointerface:: Products.CMFCore.interfaces.ICallableOpaqueItem
+ :members:
+
+.. autointerface:: Products.CMFCore.interfaces.ICallableOpaqueItemEvents
+ :members:
+
+.. autointerface:: Products.CMFCore.interfaces.IOpaqueItemManager
+ :members:
+
+
+.. _content_syndication:
+
+Content Syndication
+-------------------
+
+This interface defines the contract for content objects which can participate
+in the syndication framework provided by the :ref:`syndication_tool`.
+
+.. autointerface:: Products.CMFCore.interfaces.ISyndicatable
+ :members:
Added: Products.CMFCore/trunk/docs/api/tools.rst
===================================================================
--- Products.CMFCore/trunk/docs/api/tools.rst (rev 0)
+++ Products.CMFCore/trunk/docs/api/tools.rst 2010-04-29 16:04:17 UTC (rev 111584)
@@ -0,0 +1,244 @@
+Tool API Reference
+==================
+
+
+.. _actions_tool:
+
+Actions Tool
+------------
+
+These interfaces define the framework used to allow extensible menu actions
+via the actions tool.
+
+.. autointerface:: Products.CMFCore.interfaces.IActionProvider
+ :members:
+
+.. autointerface:: Products.CMFCore.interfaces.IActionCategory
+ :members:
+
+.. autointerface:: Products.CMFCore.interfaces.IAction
+ :members:
+
+.. autointerface:: Products.CMFCore.interfaces.IActionInfo
+ :members:
+
+.. autointerface:: Products.CMFCore.interfaces.IActionsTool
+ :members:
+
+
+.. _caching_policy_manager:
+
+Caching Policy Manager
+----------------------
+
+These interfaces define the framework used by the cache policy manager tool
+to set caching headers on content views.
+
+.. autointerface:: Products.CMFCore.interfaces.ICachingPolicy
+ :members:
+
+.. autointerface:: Products.CMFCore.interfaces.ICachingPolicyManager
+ :members:
+
+
+.. _catalog_tool:
+
+Catalog Tool
+------------
+
+These interfaces define the framework used by the catalog tool to index
+and search content. See also the interfaces for :ref:`searchable_content`.
+
+.. autointerface:: Products.CMFCore.interfaces.IIndexableObject
+ :members:
+
+.. autointerface:: Products.CMFCore.interfaces.IIndexableObjectWrapper
+ :members:
+
+.. autointerface:: Products.CMFCore.interfaces.ICatalogTool
+ :members:
+
+
+
+.. _content_type_registry:
+
+Content Type Registry
+---------------------
+
+These interfaces define the framework used by the content type registry tool
+to determine what kind of content object to create based on a MIME type or
+filename. This lookup is done when adding new items to
+:ref:`content_containers` via FTP or WebDAV.
+
+.. autointerface:: Products.CMFCore.interfaces.IContentTypeRegistryPredicate
+ :members:
+
+.. autointerface:: Products.CMFCore.interfaces.IContentTypeRegistry
+ :members:
+
+
+.. _discussion_tool:
+
+Discussion Tool
+---------------
+
+These interfaces define the framework used by the discussion tool to
+determine whether discussion is allowed for particular content objects.
+See also :ref:`discussable_content`.
+
+.. autointerface:: Products.CMFCore.interfaces.IOldstyleDiscussionTool
+ :members:
+
+.. autointerface:: Products.CMFCore.interfaces.IDiscussionTool
+ :members:
+
+
+.. _memberdata_tool:
+
+MemberData Tool
+---------------
+
+These interfaces define the framework used by the membedata tool for storing
+and querying information about a registered member.
+
+.. autointerface:: Products.CMFCore.interfaces.IMemberData
+ :members:
+
+.. autointerface:: Products.CMFCore.interfaces.IMemberDataTool
+ :members:
+
+
+.. _membership_tool:
+
+Membership Tool
+---------------
+
+This interface defines the API provided by the membership tool for finding
+site-wide information about a registered member.
+
+.. autointerface:: Products.CMFCore.interfaces.IMembershipTool
+ :members:
+
+
+.. _metadata_tool:
+
+Metadata Tool
+-------------
+
+This interface defines the API provided by the metadata tool for
+managing / querying policies about content metadata.
+
+.. autointerface:: Products.CMFCore.interfaces.IMetadataTool
+ :members:
+
+
+.. _properties_tool:
+
+Properties Tool
+---------------
+
+This interface defines the API provided by the properties tool for
+querying site-wide properties.
+
+.. autointerface:: Products.CMFCore.interfaces.IPropertiesTool
+ :members:
+
+
+.. _registration_tool:
+
+Registration Tool
+-----------------
+
+These interfaces define the framework used by the registration tool for
+managing policies about how users join the site.
+
+.. autointerface:: Products.CMFCore.interfaces.IRegistrationTool
+ :members:
+
+
+.. _skins_tool:
+
+Skins Tool
+----------
+
+These interfaces define the framework used by the skins tool for
+layering UI components to create "skins" for the site.
+
+.. autointerface:: Products.CMFCore.interfaces.IDirectoryView
+ :members:
+
+.. autointerface:: Products.CMFCore.interfaces.ISkinsContainer
+ :members:
+
+.. autointerface:: Products.CMFCore.interfaces.ISkinsTool
+ :members:
+
+
+.. _syndication_tool:
+
+Syndication Tool
+----------------
+
+These interfaces define the framework used by the syndication tool for
+managing policies about syndicating content from a given folder or collection.
+See also :ref:`content_syndication`.
+
+.. autointerface:: Products.CMFCore.interfaces.ISyndicationTool
+ :members:
+
+
+.. _types_tool:
+
+Types Tool
+----------
+
+These interfaces define the framework used by the skins type for defining
+extensible content object types.
+
+.. autointerface:: Products.CMFCore.interfaces.ITypeInformation
+ :members:
+
+.. autointerface:: Products.CMFCore.interfaces.ITypesTool
+ :members:
+
+
+.. _undo_tool:
+
+Undo Tool
+---------
+
+This interface defines the API provided undo tool for undoing changes made
+to the site.
+
+.. autointerface:: Products.CMFCore.interfaces.IUndoTool
+ :members:
+
+
+.. _url_tool:
+
+URL Tool
+--------
+
+This interfaces defines the API provided by the url tool for
+generating and resolving URLs and paths relative to the site root.
+
+.. autointerface:: Products.CMFCore.interfaces.IUndoTool
+ :members:
+
+
+.. _workflow_tool:
+
+Workflow Tool
+-------------
+
+These interfaces define the framework used by the workflow type for defining
+configurable workflows for content types. See also :ref:`content_workflow`.
+
+.. autointerface:: Products.CMFCore.interfaces.IWorkflowDefinition
+ :members:
+
+.. autointerface:: Products.CMFCore.interfaces.IWorkflowTool
+ :members:
+
+.. autointerface:: Products.CMFCore.interfaces.IConfigurableWorkflowTool
+ :members:
Added: Products.CMFCore/trunk/docs/conf.py
===================================================================
--- Products.CMFCore/trunk/docs/conf.py (rev 0)
+++ Products.CMFCore/trunk/docs/conf.py 2010-04-29 16:04:17 UTC (rev 111584)
@@ -0,0 +1,207 @@
+# -*- coding: utf-8 -*-
+#
+# CMFCore documentation build configuration file, created by
+# sphinx-quickstart on Thu Apr 29 10:34:29 2010.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import os
+#import sys
+
+# 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('.'))
+import Products
+Products.__path__.append(os.path.abspath('../Products'))
+
+# -- 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',
+ 'sphinx.ext.doctest',
+ 'sphinx.ext.intersphinx',
+ 'sphinx.ext.todo',
+ 'repoze.sphinx.autointerface',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+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 information about the project.
+project = u'CMFCore'
+copyright = u'2010, CMF Developers'
+
+# 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.
+version = '2.3'
+# The full version, including alpha/beta/rc tags.
+release = '2.3'
+
+# 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'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directory, that shouldn't be searched
+# for source files.
+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.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# 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'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+html_theme = 'default'
+
+# 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
+# "<project> v<release> documentation".
+#html_title = None
+
+# 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']
+
+# 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
+
+# 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 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
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'CMFCoredoc'
+
+
+# -- 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, documentclass [howto/manual]).
+latex_documents = [
+ ('index', 'CMFCore.tex', u'CMFCore Documentation',
+ u'CMF Developers', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# 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
+
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {'http://docs.python.org/': None}
Added: Products.CMFCore/trunk/docs/index.rst
===================================================================
--- Products.CMFCore/trunk/docs/index.rst (rev 0)
+++ Products.CMFCore/trunk/docs/index.rst 2010-04-29 16:04:17 UTC (rev 111584)
@@ -0,0 +1,15 @@
+Products.CMFCore documentation
+==============================
+
+.. toctree::
+ :maxdepth: 2
+
+ api/tools
+ api/content
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
More information about the checkins
mailing list