[Checkins] SVN: zope.event/branches/tseaver-new_style_docs/ Exemplar for proposed new style of documenting / testing ZTK packages
Tres Seaver
tseaver at palladion.com
Fri Apr 16 20:37:40 EDT 2010
Log message for revision 111012:
Exemplar for proposed new style of documenting / testing ZTK packages
- Add Sphinx documentation.
- Add Sphinx builder recipe.
- Keep the (empty) docs/_build in the checkout.
- Move narrative docs to 'docs', remove from unit tests.
The snippets in the docs get tested as part of building the HTML docs
via the 'make-docs' script.
- Move full docs out of the --long-description.
We want to be able to make full use of Sphinx markup, which confuses
the PyPI interface. Instead, the README.txt now points to the docs.
- Let 2to3 know about the new location of the docs.
- Add docs for hacking on the package.
This page is actully pretty generic. Assuming that we make it true for
any ZTK package, it might be better off in the top-level ZTK docs.
Changed:
U zope.event/branches/tseaver-new_style_docs/README.txt
U zope.event/branches/tseaver-new_style_docs/buildout.cfg
A zope.event/branches/tseaver-new_style_docs/docs/
A zope.event/branches/tseaver-new_style_docs/docs/Makefile
A zope.event/branches/tseaver-new_style_docs/docs/_build/
A zope.event/branches/tseaver-new_style_docs/docs/_static/
A zope.event/branches/tseaver-new_style_docs/docs/_templates/
A zope.event/branches/tseaver-new_style_docs/docs/api.rst
A zope.event/branches/tseaver-new_style_docs/docs/conf.py
A zope.event/branches/tseaver-new_style_docs/docs/hacking.rst
A zope.event/branches/tseaver-new_style_docs/docs/index.rst
A zope.event/branches/tseaver-new_style_docs/docs/make.bat
U zope.event/branches/tseaver-new_style_docs/setup.py
D zope.event/branches/tseaver-new_style_docs/src/zope/event/README.txt
U zope.event/branches/tseaver-new_style_docs/src/zope/event/__init__.py
U zope.event/branches/tseaver-new_style_docs/src/zope/event/tests.py
-=-
Modified: zope.event/branches/tseaver-new_style_docs/README.txt
===================================================================
--- zope.event/branches/tseaver-new_style_docs/README.txt 2010-04-17 00:29:32 UTC (rev 111011)
+++ zope.event/branches/tseaver-new_style_docs/README.txt 2010-04-17 00:37:40 UTC (rev 111012)
@@ -10,3 +10,5 @@
event dispatching systems can be built. For example, a type-based
event dispatching system that builds on ``zope.event`` can be found in
``zope.component``.
+
+Please see ``doc/index.rst`` for the documentation.
Modified: zope.event/branches/tseaver-new_style_docs/buildout.cfg
===================================================================
--- zope.event/branches/tseaver-new_style_docs/buildout.cfg 2010-04-17 00:29:32 UTC (rev 111011)
+++ zope.event/branches/tseaver-new_style_docs/buildout.cfg 2010-04-17 00:37:40 UTC (rev 111012)
@@ -1,7 +1,17 @@
[buildout]
-parts = test
develop = .
+parts =
+ test
+ sphinx
[test]
recipe = zc.recipe.testrunner
eggs = zope.event
+
+[sphinx]
+recipe = collective.recipe.sphinxbuilder
+build = ${buildout:directory}/docs/_build
+source = ${buildout:directory}/docs
+outputs = doctest html
+script-name = make-docs
+extra-paths = ${buildout:directory}/src
Added: zope.event/branches/tseaver-new_style_docs/docs/Makefile
===================================================================
--- zope.event/branches/tseaver-new_style_docs/docs/Makefile (rev 0)
+++ zope.event/branches/tseaver-new_style_docs/docs/Makefile 2010-04-17 00:37:40 UTC (rev 111012)
@@ -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/zopeevent.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/zopeevent.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: zope.event/branches/tseaver-new_style_docs/docs/api.rst
===================================================================
--- zope.event/branches/tseaver-new_style_docs/docs/api.rst (rev 0)
+++ zope.event/branches/tseaver-new_style_docs/docs/api.rst 2010-04-17 00:37:40 UTC (rev 111012)
@@ -0,0 +1,15 @@
+:mod:`zope.event` API Reference
+===============================
+
+The package exports the following API symbols.
+
+Data
+----
+
+.. autodata:: zope.event.subscribers
+
+
+Functions
+---------
+
+.. autofunction:: zope.event.notify
Added: zope.event/branches/tseaver-new_style_docs/docs/conf.py
===================================================================
--- zope.event/branches/tseaver-new_style_docs/docs/conf.py (rev 0)
+++ zope.event/branches/tseaver-new_style_docs/docs/conf.py 2010-04-17 00:37:40 UTC (rev 111012)
@@ -0,0 +1,204 @@
+# -*- coding: utf-8 -*-
+#
+# zope.event documentation build configuration file, created by
+# sphinx-quickstart on Fri Apr 16 17:22:42 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 sys, os
+
+# 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('.'))
+sys.path.append(os.path.abspath('../src'))
+
+# -- 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.coverage',
+]
+
+# 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'zope.event'
+copyright = u'2010, Zope Foundation and Contributors'
+
+# 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 = '3.4'
+# The full version, including alpha/beta/rc tags.
+release = '3.4.2'
+
+# 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 = 'zopeeventdoc'
+
+
+# -- 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', 'zopeevent.tex', u'zope.event Documentation',
+ u'Zope Foundation and Contributors', '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: zope.event/branches/tseaver-new_style_docs/docs/hacking.rst
===================================================================
--- zope.event/branches/tseaver-new_style_docs/docs/hacking.rst (rev 0)
+++ zope.event/branches/tseaver-new_style_docs/docs/hacking.rst 2010-04-17 00:37:40 UTC (rev 111012)
@@ -0,0 +1,260 @@
+Hacking on :mod:`zope.event`
+============================
+
+
+Getting the Code
+-----------------
+
+The main repository for :mod:`zope.event` is in the Zope Subversion
+repository:
+
+http://svn.zope.org/zope.event
+
+You can get a read-only Subversion checkout from there:
+
+.. code-block:: sh
+
+ $ svn checkout svn://svn.zope.org/repos/main/zope.event/trunk zope.event
+
+The project also mirrors the trunk from the Subversion repository as a
+Bazaar branch on Launchpad:
+
+https://code.launchpad.net/zope.event
+
+You can branch the trunk from there using Bazaar:
+
+.. code-block:: sh
+
+ $ bzr branch lp:zope.event
+
+
+Running the tests in a ``virtualenv``
+-------------------------------------
+
+If you use the ``virtualenv`` package to create lightweight Python
+development environments, you can run the tests using nothing more
+than the ``python`` binary in a virtualenv. First, create a scratch
+environment:
+
+.. code-block:: sh
+
+ $ /path/to/virtualenv --no-site-packages /tmp/hack-zope.event
+
+Next, get this package registered as a "development egg" in the
+environment:
+
+.. code-block:: sh
+
+ $ /tmp/hack-zope.event/bin/python setup.py develop
+
+Finally, run the tests using the build-in ``setuptools`` testrunner:
+
+.. code-block:: sh
+
+ $ /tmp/hack-zope.event/bin/python setup.py test
+ running test
+ ...
+ test_empty (zope.event.tests.Test_notify) ... ok
+ test_not_empty (zope.event.tests.Test_notify) ... ok
+
+ ----------------------------------------------------------------------
+ Ran 2 tests in 0.000s
+
+ OK
+
+If you have the :mod:`nose` package installed in the virtualenv, you can
+use its testrunner too:
+
+.. code-block:: sh
+
+ $ /tmp/hack-zope.event/bin/easy_install nose
+ ...
+ $ /tmp/hack-zope.event/bin/python setup.py nosetests
+ running nosetests
+ ...
+ ----------------------------------------------------------------------
+ Ran 3 tests in 0.011s
+
+ OK
+
+or:
+
+.. code-block:: sh
+
+ $ /tmp/hack-zope.event/bin/nosetests
+ ...
+ ----------------------------------------------------------------------
+ Ran 3 tests in 0.011s
+
+ OK
+
+If you have the :mod:`coverage` pacakge installed in the virtualenv,
+you can see how well the tests cover the code:
+
+.. code-block:: sh
+
+ $ /tmp/hack-zope.event/bin/easy_install nose coverage
+ ...
+ $ /tmp/hack-zope.event/bin/python setup.py nosetests \
+ --with coverage --cover-package=zope.event
+ running nosetests
+ ...
+ Name Stmts Exec Cover Missing
+ ------------------------------------------
+ zope.event 5 5 100%
+ ----------------------------------------------------------------------
+ Ran 3 tests in 0.019s
+
+ OK
+
+
+Building the documentation in a ``virtualenv``
+----------------------------------------------
+
+:mod:`zope.event` uses the nifty :mod:`Sphinx` documentation system
+for building its docs. Using the same virtualenv you set up to run the
+tests, you can build the docs:
+
+.. code-block:: sh
+
+ $ /tmp/hack-zope.event/bin/easy_install Sphinx
+ ...
+ $ cd docs
+ $ PATH=/tmp/hack-zope.event/bin:$PATH make html
+ sphinx-build -b html -d _build/doctrees . _build/html
+ ...
+ build succeeded.
+
+ Build finished. The HTML pages are in _build/html.
+
+You can also test the code snippets in the documentation:
+
+.. code-block:: sh
+
+ $ PATH=/tmp/hack-zope.event/bin:$PATH make doctest
+ sphinx-build -b doctest -d _build/doctrees . _build/doctest
+ ...
+ running tests...
+
+ Document: index
+ ---------------
+ 1 items passed all tests:
+ 17 tests in default
+ 17 tests in 1 items.
+ 17 passed and 0 failed.
+ Test passed.
+
+ Doctest summary
+ ===============
+ 17 tests
+ 0 failures in tests
+ 0 failures in setup code
+ build succeeded.
+ Testing of doctests in the sources finished, look at the \
+ results in _build/doctest/output.txt.
+
+
+Running the tests using :mod:`zc.buildout`
+-------------------------------------------
+
+:mod:`zope.event` ships with its own :file:`buildout.cfg` file and
+:file:`bootstrap.py` for setting up a development buildout:
+
+.. code-block:: sh
+
+ $ /path/to/python2.6 bootstrap.py
+ ...
+ Generated script '.../bin/buildout'
+ $ bin/buildout
+ Develop: '/home/tseaver/projects/Zope/BTK/event/.'
+ ...
+ Generated script '.../bin/sphinx-quickstart'.
+ Generated script '.../bin/sphinx-build'.
+
+You can now run the tests:
+
+.. code-block:: sh
+
+ $ bin/test --all
+ Running zope.testing.testrunner.layer.UnitTests tests:
+ Set up zope.testing.testrunner.layer.UnitTests in 0.000 seconds.
+ Ran 2 tests with 0 failures and 0 errors in 0.000 seconds.
+ Tearing down left over layers:
+ Tear down zope.testing.testrunner.layer.UnitTests in 0.000 seconds.
+
+
+Building the documentation using :mod:`zc.buildout`
+---------------------------------------------------
+
+The :mod:`zope.event` buildout creates the necessary scripts to build
+the documentation, including testing its code snippets:
+
+.. code-block:: sh
+
+ $ bin/make-docs
+ .../bin/sphinx-build -b doctest -d .../docs/_build/doctrees .../docs .../docs/_build/doctest
+ running tests...
+
+ Document: index
+ ---------------
+ 1 items passed all tests:
+ 17 tests in default
+ 17 tests in 1 items.
+ 17 passed and 0 failed.
+ Test passed.
+
+ Doctest summary
+ ===============
+ 17 tests
+ 0 failures in tests
+ 0 failures in setup code
+ build succeeded.
+ Testing of doctests in the sources finished, look at the results in .../docs/_build/doctest/output.txt.
+ .../bin/sphinx-build -b html -d .../docs/_build/doctrees .../docs .../docs/_build/html
+ ...
+ build succeeded.
+
+ Build finished. The HTML pages are in .../docs/_build/html.
+
+
+Submitting a Bug Report
+-----------------------
+
+:mod:`zope.event` tracks its bugs on Launchpad:
+
+https://bugs.launchpad.net/zope.event
+
+Please submit bug reports and feature requests there.
+
+
+Sharing Your Changes
+--------------------
+
+.. note::
+
+ Please ensure that all tests are passing before you submit your code.
+ If possible, your submission should include new tests for new features
+ or bug fixes, although it is possible that you may have tested your
+ new code by updating existing tests.
+
+If you got a read-only checkout from the Subversion repository, and you
+have made a change you would like to share, the best route is to let
+Subversion help you make a patch file:
+
+.. code-block:: sh
+
+ $ svn diff > zope.event-cool_feature.patch
+
+You can then upload that patch file as an attachment to a Launchpad bug
+report.
+
+If you branched the code from Launchpad using Bazaar, you have another
+option: you can "push" your branch to Launchpad:
+
+.. code-block:: sh
+
+ $ bzr push lp:~tseaver/zope.event/cool_feature
+
+After pushing your branch, you can link it to a bug report on Launchpad,
+or request that the maintainers merge your branch using the Launchpad
+"merge request" feature.
Added: zope.event/branches/tseaver-new_style_docs/docs/index.rst
===================================================================
--- zope.event/branches/tseaver-new_style_docs/docs/index.rst (rev 0)
+++ zope.event/branches/tseaver-new_style_docs/docs/index.rst 2010-04-17 00:37:40 UTC (rev 111012)
@@ -0,0 +1,102 @@
+:mod:`zope.event` Documentation
+===============================
+
+This package provides a simple event system on which
+application-specific event systems can be built.
+
+Application code can generate events without being concerned about the
+event-processing frameworks that might handle the events.
+
+Events are objects that represent something happening in a system.
+They are used to extend processing by providing processing plug
+points.
+
+The package has a list of subscribers. Application code can manage
+subscriptions by manipulating this list. For the examples here, we'll
+save the current contents away and empty the list. We'll restore the
+contents when we're done with our examples.
+
+.. doctest::
+
+ >>> import zope.event
+ >>> old_subscribers = zope.event.subscribers[:]
+ >>> del zope.event.subscribers[:]
+
+The package provides a :func:`notify` function, which is used to
+notify subscribers that something has happened:
+
+.. doctest::
+
+ >>> class MyEvent:
+ ... pass
+
+ >>> event = MyEvent()
+ >>> zope.event.notify(event)
+
+The notify function is called with a single object, which we call an
+event. Any object will do:
+
+.. doctest::
+
+ >>> zope.event.notify(None)
+ >>> zope.event.notify(42)
+
+An extremely trivial subscription mechanism is provided. Subscribers
+are simply callback functions:
+
+.. doctest::
+
+ >>> def f(event):
+ ... print 'got:', event
+
+that are put into the subscriptions list:
+
+.. doctest::
+
+ >>> zope.event.subscribers.append(f)
+
+ >>> zope.event.notify(42)
+ got: 42
+
+ >>> def g(event):
+ ... print 'also got:', event
+
+ >>> zope.event.subscribers.append(g)
+
+ >>> zope.event.notify(42)
+ got: 42
+ also got: 42
+
+To unsubscribe, simply remove a subscriber from the list:
+
+.. doctest::
+
+ >>> zope.event.subscribers.remove(f)
+ >>> zope.event.notify(42)
+ also got: 42
+
+Generally, application frameworks will provide more sophisticated
+subscription mechanisms that build on this simple mechanism. The
+frameworks will install subscribers that then dispatch to other
+subscribers based on event types or data.
+
+We're done, so we'll restore the subscribers:
+
+.. doctest::
+
+ >>> zope.event.subscribers[:] = old_subscribers
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ api
+ hacking
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
Added: zope.event/branches/tseaver-new_style_docs/docs/make.bat
===================================================================
--- zope.event/branches/tseaver-new_style_docs/docs/make.bat (rev 0)
+++ zope.event/branches/tseaver-new_style_docs/docs/make.bat 2010-04-17 00:37:40 UTC (rev 111012)
@@ -0,0 +1,113 @@
+ at ECHO OFF
+
+REM Command file for Sphinx documentation
+
+set SPHINXBUILD=sphinx-build
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+ set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+ :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 over 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
+ goto end
+)
+
+if "%1" == "clean" (
+ for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+ del /q /s %BUILDDIR%\*
+ goto end
+)
+
+if "%1" == "html" (
+ %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+ goto end
+)
+
+if "%1" == "dirhtml" (
+ %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+ goto end
+)
+
+if "%1" == "pickle" (
+ %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+ echo.
+ echo.Build finished; now you can process the pickle files.
+ goto end
+)
+
+if "%1" == "json" (
+ %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+ echo.
+ echo.Build finished; now you can process the JSON files.
+ goto end
+)
+
+if "%1" == "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.
+ goto end
+)
+
+if "%1" == "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\zopeevent.qhcp
+ echo.To view the help file:
+ echo.^> assistant -collectionFile %BUILDDIR%\qthelp\zopeevent.ghc
+ goto end
+)
+
+if "%1" == "latex" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ echo.
+ echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "changes" (
+ %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+ echo.
+ echo.The overview file is in %BUILDDIR%/changes.
+ goto end
+)
+
+if "%1" == "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.
+ goto end
+)
+
+if "%1" == "doctest" (
+ %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+ echo.
+ echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+ goto end
+)
+
+:end
Modified: zope.event/branches/tseaver-new_style_docs/setup.py
===================================================================
--- zope.event/branches/tseaver-new_style_docs/setup.py 2010-04-17 00:29:32 UTC (rev 111011)
+++ zope.event/branches/tseaver-new_style_docs/setup.py 2010-04-17 00:37:40 UTC (rev 111012)
@@ -30,7 +30,7 @@
# Python 3 support:
extra = dict(
use_2to3=True,
- convert_2to3_doctests=['src/zope/event/README.txt'],
+ convert_2to3_doctests=['docs/index.rst'],
)
def read(*rnames):
@@ -46,8 +46,6 @@
author_email='zope-dev at zope.org',
long_description=(
read('README.txt')
- + '\n\n.. contents::\n\n' +
- read('src', 'zope', 'event', 'README.txt')
+ '\n' +
read('CHANGES.txt')
),
Deleted: zope.event/branches/tseaver-new_style_docs/src/zope/event/README.txt
===================================================================
--- zope.event/branches/tseaver-new_style_docs/src/zope/event/README.txt 2010-04-17 00:29:32 UTC (rev 111011)
+++ zope.event/branches/tseaver-new_style_docs/src/zope/event/README.txt 2010-04-17 00:37:40 UTC (rev 111012)
@@ -1,73 +0,0 @@
-Events
-======
-
-This package provides a simple event system on which
-application-specific event systems can be built.
-
-Application code can generate events without being concerned about the
-event-processing frameworks that might handle the events.
-
-Events are objects that represent something happening in a system.
-They are used to extend processing by providing processing plug
-points.
-
-The package has a list of subscribers. Application code can manage
-subscriptions by manipulating this list. For the examples here, we'll
-save the current contents away and empty the list. We'll restore the
-contents when we're done with our examples.
-
- >>> import zope.event
- >>> old_subscribers = zope.event.subscribers[:]
- >>> del zope.event.subscribers[:]
-
-The package provides a `notify` function, which is used to
-notify subscribers that something has happened:
-
- >>> class MyEvent:
- ... pass
-
- >>> event = MyEvent()
- >>> zope.event.notify(event)
-
-The notify function is called with a single object, which we call an
-event. Any object will do:
-
- >>> zope.event.notify(None)
- >>> zope.event.notify(42)
-
-An extremely trivial subscription mechanism is provided. Subscribers
-are simply callback functions:
-
- >>> def f(event):
- ... print 'got:', event
-
-that are put into the subscriptions list:
-
- >>> zope.event.subscribers.append(f)
-
- >>> zope.event.notify(42)
- got: 42
-
- >>> def g(event):
- ... print 'also got:', event
-
- >>> zope.event.subscribers.append(g)
-
- >>> zope.event.notify(42)
- got: 42
- also got: 42
-
-To unsubscribe, simply remove a subscriber from the list:
-
- >>> zope.event.subscribers.remove(f)
- >>> zope.event.notify(42)
- also got: 42
-
-Generally, application frameworks will provide more sophisticated
-subscription mechanisms that build on this simple mechanism. The
-frameworks will install subscribers that then dispatch to other
-subscribers based on event types or data.
-
-We're done, so we'll restore the subscribers:
-
- >>> zope.event.subscribers[:] = old_subscribers
Modified: zope.event/branches/tseaver-new_style_docs/src/zope/event/__init__.py
===================================================================
--- zope.event/branches/tseaver-new_style_docs/src/zope/event/__init__.py 2010-04-17 00:29:32 UTC (rev 111011)
+++ zope.event/branches/tseaver-new_style_docs/src/zope/event/__init__.py 2010-04-17 00:37:40 UTC (rev 111012)
@@ -11,13 +11,21 @@
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
-"""base event system implementation
+""" Base event system implementation
-$Id$
"""
+#: Applications may register for notification of events by appending a
+#: callable to the ``subscribers`` list.
+#:
+#: Each subscriber takes a single argument, which is the event object
+#: being published.
+#:
+#: Subscribers **MUST NOT** raise exceptions.
subscribers = []
def notify(event):
+ """ Notify all subscribers of ``event``.
+ """
for subscriber in subscribers:
subscriber(event)
Modified: zope.event/branches/tseaver-new_style_docs/src/zope/event/tests.py
===================================================================
--- zope.event/branches/tseaver-new_style_docs/src/zope/event/tests.py 2010-04-17 00:29:32 UTC (rev 111011)
+++ zope.event/branches/tseaver-new_style_docs/src/zope/event/tests.py 2010-04-17 00:37:40 UTC (rev 111012)
@@ -14,7 +14,6 @@
""" Test the event system
"""
import unittest
-import doctest
class Test_notify(unittest.TestCase):
@@ -46,5 +45,4 @@
def test_suite():
return unittest.TestSuite((
unittest.makeSuite(Test_notify),
- doctest.DocFileSuite('README.txt'),
))
More information about the checkins
mailing list