[Checkins] SVN: Products.GenericSetup/trunk/ Sphinx-ify docs at egg level (rather than in package).
Tres Seaver
tseaver at palladion.com
Sat Sep 27 13:35:07 EDT 2008
Log message for revision 91562:
Sphinx-ify docs at egg level (rather than in package).
Changed:
U Products.GenericSetup/trunk/README.txt
A Products.GenericSetup/trunk/docs/
A Products.GenericSetup/trunk/docs/.static/
A Products.GenericSetup/trunk/docs/.templates/
A Products.GenericSetup/trunk/docs/Makefile
A Products.GenericSetup/trunk/docs/conf.py
A Products.GenericSetup/trunk/docs/glossary.rst
A Products.GenericSetup/trunk/docs/handlers.rst
A Products.GenericSetup/trunk/docs/index.rst
A Products.GenericSetup/trunk/docs/install.rst
A Products.GenericSetup/trunk/docs/profiles.rst
-=-
Modified: Products.GenericSetup/trunk/README.txt
===================================================================
--- Products.GenericSetup/trunk/README.txt 2008-09-27 15:45:41 UTC (rev 91561)
+++ Products.GenericSetup/trunk/README.txt 2008-09-27 17:35:07 UTC (rev 91562)
@@ -1 +1 @@
-(See Products/GenericSetup/README.txt).
+(See docs/index.rst).
Property changes on: Products.GenericSetup/trunk/docs
___________________________________________________________________
Name: svn:ignore
+ .build
Added: Products.GenericSetup/trunk/docs/Makefile
===================================================================
--- Products.GenericSetup/trunk/docs/Makefile (rev 0)
+++ Products.GenericSetup/trunk/docs/Makefile 2008-09-27 17:35:07 UTC (rev 91562)
@@ -0,0 +1,70 @@
+# 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 pickle htmlhelp latex changes linkcheck
+
+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 " 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."
+
+pickle:
+ mkdir -p .build/pickle .build/doctrees
+ $(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."
+
+web: pickle
+
+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."
Added: Products.GenericSetup/trunk/docs/conf.py
===================================================================
--- Products.GenericSetup/trunk/docs/conf.py (rev 0)
+++ Products.GenericSetup/trunk/docs/conf.py 2008-09-27 17:35:07 UTC (rev 91562)
@@ -0,0 +1,179 @@
+# -*- coding: utf-8 -*-
+#
+# Products.GenericSetup documentation build configuration file, created by
+# sphinx-quickstart on Sat Sep 27 12:26:01 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, 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.
+#sys.path.append(os.path.abspath('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 = ['sphinx.ext.autodoc']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['.templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General substitutions.
+project = 'Products.GenericSetup'
+copyright = '2008, Zope CMF Developers'
+
+# The default replacements for |version| and |release|, also used in various
+# other places throughout the built documents.
+#
+# The short X.Y version.
+version = '1.5'
+# The full version, including alpha/beta/rc tags.
+release = '1.5.0dev'
+
+# 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 directories, that shouldn't be searched
+# for source files.
+#exclude_dirs = []
+
+# 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'
+
+
+# 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 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 (within the static path) 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, the reST sources are included in the HTML build as _sources/<name>.
+#html_copy_source = 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 = 'ProductsGenericSetupdoc'
+
+
+# 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 = [
+ ('index', 'ProductsGenericSetup.tex', 'Products.GenericSetup Documentation',
+ 'Zope 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
Added: Products.GenericSetup/trunk/docs/glossary.rst
===================================================================
--- Products.GenericSetup/trunk/docs/glossary.rst (rev 0)
+++ Products.GenericSetup/trunk/docs/glossary.rst 2008-09-27 17:35:07 UTC (rev 91562)
@@ -0,0 +1,32 @@
+Glossary
+========
+
+.. glossary::
+
+ site
+ The instance in the Zope URL space which defines a "zone of service"
+ for a set of tools.
+
+ dotted name
+ The Pythonic representation of the "path" to a given function /
+ module, e.g. ``Products.GenericSetup.tool.exportToolset``.
+
+ profile
+ A "preset" configuration of a site, defined on the filesystem
+ or in a tarball.
+
+ base profile
+ Profiles which represent the entire configuration of a given
+ site, and have no dependencies.
+
+ extension profile
+ Profile fragments are used to modify a site created from a given
+ :term:`base profile`. They can be shipped with add-on products or
+ used for customization steps. Importing an :term:`extension
+ profile` adds or overwrites existing settings in a fine-grained
+ way. An :term:`extension profile` cannot be exported.
+
+ snapshot
+ A profile which captures the state of the site's configuration
+ at a point in time (e.g., immediately after creation of the site,
+ or after importing an :term:`extension profile`.
Added: Products.GenericSetup/trunk/docs/handlers.rst
===================================================================
--- Products.GenericSetup/trunk/docs/handlers.rst (rev 0)
+++ Products.GenericSetup/trunk/docs/handlers.rst 2008-09-27 17:35:07 UTC (rev 91562)
@@ -0,0 +1,99 @@
+.. _writing-handlers:
+
+How-to: Writing setup handlers for ``Products.GenericSetup``
+============================================================
+
+If your products subclass existing tools or provide new tools (or new
+sub-object classes) they might need their own setup handlers in order to
+make use of GenericSetup.
+
+Step 1:
+-------
+
+Identify those classes in your product that need their own setup handlers.
+In theory you don't need your own handlers for classes which implement a
+CMF tool interface that already has a setup adapter. In practice the
+adapters shipped with the CMF sometimes use methods that are not part of
+the interface, so you have to verify they really work for your classes.
+
+Step 2:
+-------
+
+Make sure those classes that need setup handlers have Zope3 style
+interfaces. Later you will write setup adapters for those interfaces.
+
+Step 3:
+-------
+
+Create an ``exportimport`` module inside your product. If you plan to write
+many setup handlers this can be a sub-package.
+
+Step 4:
+-------
+
+Decide which kind of setup handler you need:
+
+body adapter
+ For objects represented by a complete file body. Provides
+ ``Products.GenericSetup.interfaces.IBody``.
+
+XML adapter
+ A 'body adapter' in XML format. Also provides
+ ``Products.GenericSetup.interfaces.IBody``, but has its own
+ base class because XML is the preferred format.
+
+node adapter
+ For sub-objects represented by an XML node of the parent's XML document.
+ Provides ``Products.GenericSetup.interfaces.INode``. This is useful for
+ sub-objects of complex tools. Custom catalog index or action classes
+ need this kind of adapter.
+
+import and export steps
+ Top level handlers that can be registered as import step or export step
+ and call the body adapters. Maybe these will become obsolete for tools,
+ but currently they are required.
+
+If you use the base classes from :mod:`Products.GenericSetup.utils`, XML and
+node adapters are implemented in a very similar way. Both can mix in
+``ObjectManagerHelpers`` and ``PropertyManagerHelpers``.
+
+Step 5:
+-------
+
+:mod:`Products.CMFCore.exportimport` contains many examples for XML and
+node adapters. If you need a pure body adapter,
+:mod:`Products.GenericSetup.PythonScripts` would be a good
+example. Follow those examples and write your own multi adapter, register
+it for the interface of your class and for
+``Products.GenericSetup.interfaces.ISetupEnviron`` and don't forget
+to write unit tests.
+
+Adapters follow the convention that ``self.context`` is always the primary
+adapted object, so the minimal setup context (``ISetupEnviron``) used in these
+multi adapters is ``self.environ``.
+
+XML and body adapters are always also small node adapters. This way the
+XML file of the container contains the information that is necessary to
+create an empty object. The handler of the container has to set up
+sub-objects before we can adapt them and configure them with their own
+handlers. The base classes in :mod:`Products.GenericSetup.utils`
+will care about that.
+
+Step 6:
+-------
+
+If your adapter is a top-level adapter (e.g for a tool), you need import
+and export steps that know how to use the adapter. Again there are many
+examples in :mod:`Products.CMFCore.exportimport`.
+
+To make those steps available you have to add them to ``export_steps.xml``
+and ``import_steps.xml`` of a setup profile and to load that profile into the
+setup tool.
+
+Step 7:
+-------
+
+Now you are done. To ship default settings with your product, make your
+settings through the ZMI (or set your stuff up the old way if you have old
+setup code like an ``Install.py``) and export your settings using the setup
+tool.
Added: Products.GenericSetup/trunk/docs/index.rst
===================================================================
--- Products.GenericSetup/trunk/docs/index.rst (rev 0)
+++ Products.GenericSetup/trunk/docs/index.rst 2008-09-27 17:35:07 UTC (rev 91562)
@@ -0,0 +1,68 @@
+Overview of GenericSetup
+------------------------
+
+This product provides a mini-framework for expressing the configured
+state of a Zope Site as a set of filesystem artifacts. These artifacts
+consist of declarative XML files, which spell out the configuration
+settings for each "tool" in the site , and supporting scripts / templates,
+in their "canonical" filesystem representations.
+
+.. contents::
+
+
+Configurations Included
+-----------------------
+
+The ``setup_tool`` knows how to export / import configurations and scripts
+for the following components of a site:
+
+- itself :)
+
+- removal / creation of specified tools
+
+- the role / permission map on the "site" object (its parent)
+
+- properties of the site object
+
+- "Placeful" utilities and adapters registered in the local
+ site manager. Placeless utilities can only be imported.
+
+
+Extending The Tool
+------------------
+
+Third-party products extend the tool by registering handlers for
+import / export of their unique tools.
+
+.. seealso::
+
+ See :ref:`writing-handlers` for a step by step how-to.
+
+Providing Profiles
+------------------
+
+GenericSetup doesn't ship with any profile. They have to be provided by
+third-party products and depend on the registered handlers.
+
+.. seealso::
+
+ See :ref:`about-profiles` for more details.
+
+Other Documentation
+-------------------
+
+.. toctree::
+ :maxdepth: 2
+
+ install
+ handlers
+ profiles
+ glossary
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
Added: Products.GenericSetup/trunk/docs/install.rst
===================================================================
--- Products.GenericSetup/trunk/docs/install.rst (rev 0)
+++ Products.GenericSetup/trunk/docs/install.rst 2008-09-27 17:35:07 UTC (rev 91562)
@@ -0,0 +1,25 @@
+Installing :mod:`Products.GenericSetup`
+=======================================
+
+Installation via :command:`easy_install`
+----------------------------------------
+
+GenericSetup can be installed using the :mod:`setuptools` utility,
+:command:`easy_install`, into the ``site-packages`` directory of your
+Python installation::
+
+ $ bin/easy_install Products.GenericSetup
+
+Installation via :mod:`zc.buildout`
+-----------------------------------
+
+TBD
+
+Manual Installation
+-------------------
+
+To install this package manually, without using :mod:`setuptools`,
+simply untar the package file downloaded from the PyPI site and look for
+the folder named ``GenericSetup`` underneath the ``Products`` folder at the
+root of the extracted tarball. Copy or link this ``GenericSetup``
+folder into the ``Products`` folder of your Zope2 instance and restart Zope.
Added: Products.GenericSetup/trunk/docs/profiles.rst
===================================================================
--- Products.GenericSetup/trunk/docs/profiles.rst (rev 0)
+++ Products.GenericSetup/trunk/docs/profiles.rst 2008-09-27 17:35:07 UTC (rev 91562)
@@ -0,0 +1,101 @@
+.. _about-profiles:
+
+About Profiles
+==============
+
+Overview
+--------
+
+``GenericSetup`` uses two different kinds of profiles: a :term:`base
+profile` captures the entire state of the site, while an :term:`extension
+profile` represents an add-on / delta to be applied to the site's
+configuration.
+
+
+Registering Profiles
+--------------------
+
+By convention profiles are stored in a ``profiles`` directory within a
+Zope2 product. They have to be registered explicitly using either the
+:meth:`Products.GenericSetup.profile_registry.registerProfile` API or the
+equivalent ``genericsetup::registerProfile`` ZCML directive.
+
+Here is example ZCML for a Zope2 product, ``MyProduct``, which extends
+another product, ``BaseProduct``::
+
+ <genericsetup:registerProfile
+ name="install"
+ title="Install MyProduct Extension"
+ description="Adds local settings necessary for MyProduct."
+ provides="Products.GenericSetup.interfaces.EXTENSION"
+ for="Products.BaseProduct.interfaces.IBaseRoot"
+ />
+
+.. seealso::
+
+ See :class:`Products.GenericSetup.zcml.IRegisterProfileDirective` for
+ further details.
+
+Alternatively, profiles can be registered by calling the
+:func:`Products.GenericSetup.profile_registry.registerProfile` API.
+
+Here is the code for the same example::
+
+ from Products.BaseProduct.interfaces import IBaseRoot
+ from Products.GenericSetup import EXTENSION
+ from Products.GenericSetup import profile_registry
+
+ profile_registry.registerProfile(
+ name='install',
+ title='Install MyProduct Extension',
+ description='Adds local settings necessary for MyProduct.',
+ path='profiles/install',
+ product='Products.MyProduct',
+ profile_type=EXTENSION,
+ for_=IBaseRoot)
+
+.. seealso::
+
+ See IProfileRegistry.registerProfile for further details.
+
+.. note::
+ Using this API for product initialization is deprecated.
+
+Update Directives
+-----------------
+
+For some XML elements there are additional attributes and values to
+specify update directives. They are only useful for extension profiles and
+you will never see them in snapshots and exports.
+
+The following directives are generally useful for container elements and
+implemented by some setup handlers. Products using GenericSetup can also
+implement other update directives.
+
+``id="*"`` wildcard
+
+ Updates all existing items in the container with the same settings.
+
+``remove``
+
+ Removes the specified item if it exists.
+
+``insert-before`` and ``insert-after``
+
+ ``insert-before`` and ``insert-after`` specify the position of a new
+ item relative to an existing item. If they are omitted or not valid,
+ items are appended. You can also use ``*`` as wildcard. This will
+ insert the new item at the top (before all existing items) or the
+ bottom (after all existing items). If an item with the given ID exists
+ already, it is moved to the specified position. This directive makes
+ only sense for ordered containers.
+
+Other Special Directives
+------------------------
+
+``purge``
+
+ By default existing settings are purged before applying settings from
+ base profiles. Extension profiles are applied in update mode. This
+ directive overrides the default behavior. If True the existing settings
+ of the current object are always purged, if False they are not purged.
More information about the Checkins
mailing list