-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

This kind of goes with Lennart's frustration about trying to port the
ZTK packages, or a core subset, to Python 3.

I would like to see the ZTK packages have really excellent
documentation, as well as 100% test coverage.  I think we need to look
at refactoring how the testing story is done to get both needs
satisfied:  trying to achieve both with a single set of doctests is
pretty near impossible:

- - Testing setup and teardown code obscures the narrative flow / intent
  of the documentation.

- - Edge case testing *really* obscures the same.

- - Test coverage suffers, because it is hard to write edge-case tests
  in doctest.

- - Porting the doctests where people have tried to juggle both goals
  across Python versions is a mess.

The refactoring I would like to see happen is to move the main narrative
documentation into a separate, Sphinx-driven 'docs' directory in each
ZTK package.  As part of this move, we can start adding some of the
really nice Sphinx features (cross references, indexing, auto-generation
of API reference information, etc.).

We can still leave the "main line" of the code illustrated using
doctest-style blocks:  Sphinx has nice support for testing those blocks
*while building the docs*.  At the end of this part of the change, each
package would have a much improved documentation set, with tested
examples.  At the end of the process, we would be able to put the docs
for each package into an "intersphinx" tree underneath the main ZTK
docs, which could serve as the gateway into them.

The trickier testing bits we would re-write as super thorough, no
shortcuts-taken unit tests:  one testcase class per class (or API
function) under test, at least one method per class-under-test method,
with more preferred to get all code paths / preconditions covered.  The
goal here would be to comment out the doctests from the test_suites and
get the code to 100% coverage using pure unit tests.  Meanwhile, the
doctests would be refactored into the Sphinx documentation, losing all
the bits which obscure their intent as documentation.

I would say that the risks here are slight, given that aiming for 100%
test coverage is likely to catch any oversights made during porting to
the new style.  The amount of work for any given package is fairly-well
contained, I think:  most of the effort will be in reverse-engineering
the intent of the "edge-case" tests.

I made a sketch at what these changes would look for the zope.event
package like on a branch in Subversion:

  http://svn.zope.org/zope.event/branches/tseaver-new_style_docs

I select zope.event largely because it is small enough that the scope of
the structural changes wouldn't be lost in the diffs for the actual
tests (and also because I didn't want to do the work for a bigger
package before getting feedback).

The rendered docs from that branch are here:

  http://palladion.com/static/zope.event-docs/

I pushed the bzr branch to Launchpad, to let you see the kinds of
changes I made to get there (our viewcvs story is not nearly as easy to
review as the Launchpad changeset view):

  https://code.launchpad.net/~tseaver/zope.event/new_style_docs

I am attaching an annotated diff for those who would prefer to see the
changes in that format.

I would say that this cleanup effort should start at the "bottom" layers
of the ZTK, dependency-wise (zope.interface, zope.component, etc.) and
move "upwards" (in the depenency sense) over time.

Thoughts?



Tres.
- --
===================================================================
Tres Seaver          +1 540-429-0999          tsea...@palladion.com
Palladion Software   "Excellence by Design"    http://palladion.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkvJEakACgkQ+gerLs4ltQ6X/wCgueT8RD10bKrM4OInF0sIj/Tk
rs4AnAiQlBWZoHd35ti0tPlae/JsVgvC
=K8N0
-----END PGP SIGNATURE-----
The first patch adds docs generated via 'sphinx-quickstart.


------------------------------------------------------------
revno: 37
committer: Tres Seaver <tsea...@agendaless.com>
branch nick: event
timestamp: Fri 2010-04-16 18:00:23 -0400
message:
  Add Sphinx documentation.
diff:

=== added directory 'docs'
=== added file 'docs/Makefile'
--- docs/Makefile	1970-01-01 00:00:00 +0000
+++ docs/Makefile	2010-04-16 22:00:23 +0000
@@ -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 file 'docs/make.bat'
--- docs/make.bat	1970-01-01 00:00:00 +0000
+++ docs/make.bat	2010-04-16 22:00:23 +0000
@@ -0,0 +1,113 @@
+...@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
=== added file 'docs/conf.py'
--- docs/conf.py	1970-01-01 00:00:00 +0000
+++ docs/conf.py	2010-04-16 22:00:23 +0000
@@ -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 directory 'docs/_static'
=== added directory 'docs/_templates'


The top-level README.txt points to the new docs.


=== modified file 'README.txt'
--- README.txt	2009-03-03 20:41:25 +0000
+++ README.txt	2010-04-16 22:00:23 +0000
@@ -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.

=== added file 'docs/index.rst'
--- docs/index.rst	1970-01-01 00:00:00 +0000
+++ docs/index.rst	2010-04-16 22:00:23 +0000
@@ -0,0 +1,101 @@
+: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
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`


The API docs are geenereated using Sphinx's 'autodoc' extenion.


=== added file 'docs/api.rst'
--- docs/api.rst	1970-01-01 00:00:00 +0000
+++ docs/api.rst	2010-04-16 22:00:23 +0000
@@ -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


Docstrings are added / cleaned up, with specially-formatted comments
for autodoc-aware API data members.


=== modified file 'src/zope/event/__init__.py'
--- src/zope/event/__init__.py	2010-04-06 06:48:50 +0000
+++ src/zope/event/__init__.py	2010-04-16 22:00:23 +0000
@@ -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)
------------------------------------------------------------


Use the 'collective.recipe.sphinxbuilder' to run doctest snippets
in docs and generate the HTML.


revno: 38
committer: Tres Seaver <tsea...@agendaless.com>
branch nick: event
timestamp: Fri 2010-04-16 18:36:59 -0400
message:
  Add Sphinx builder recipe.
diff:
=== modified file 'buildout.cfg'
--- buildout.cfg	2007-02-19 10:33:04 +0000
+++ buildout.cfg	2010-04-16 22:36:59 +0000
@@ -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
------------------------------------------------------------




revno: 39
committer: Tres Seaver <tsea...@agendaless.com>
branch nick: event
timestamp: Fri 2010-04-16 19:00:41 -0400
message:
  Keep the (empty) docs/_build in the checkout.
diff:
=== added directory 'docs/_build'
------------------------------------------------------------


Remove the already-migrated narrative content out of the
package-local README.txt.


revno: 40
committer: Tres Seaver <tsea...@agendaless.com>
branch nick: event
timestamp: Fri 2010-04-16 19:20:30 -0400
message:
  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.
diff:
=== removed file 'src/zope/event/README.txt'
--- src/zope/event/README.txt	2007-05-03 20:53:04 +0000
+++ src/zope/event/README.txt	1970-01-01 00:00:00 +0000
@@ -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


Don't try to test it during unit testing, either.

=== modified file 'src/zope/event/tests.py'
--- src/zope/event/tests.py	2010-04-16 21:19:19 +0000
+++ src/zope/event/tests.py	2010-04-16 23:20:30 +0000
@@ -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'),
         ))
------------------------------------------------------------




revno: 41
committer: Tres Seaver <tsea...@agendaless.com>
branch nick: event
timestamp: Fri 2010-04-16 20:25:40 -0400
message:
  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.
diff:
=== modified file 'setup.py'
--- setup.py	2010-04-06 06:48:50 +0000
+++ setup.py	2010-04-17 00:25:40 +0000
@@ -46,8 +46,6 @@
     author_email='zope-dev@zope.org',
     long_description=(
         read('README.txt')
-        + '\n\n.. contents::\n\n' +
-        read('src', 'zope', 'event', 'README.txt')
         + '\n' +
         read('CHANGES.txt')
         ),
------------------------------------------------------------




revno: 42
committer: Tres Seaver <tsea...@agendaless.com>
branch nick: event
timestamp: Fri 2010-04-16 20:25:55 -0400
message:
  Let 2to3 know about the new location of the docs.
diff:
=== modified file 'setup.py'
--- setup.py	2010-04-17 00:25:40 +0000
+++ setup.py	2010-04-17 00:25:55 +0000
@@ -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):
------------------------------------------------------------


Add mostly-generic docs for folks who might hack on the code.  If we make
these true for all ZTK packages, then they could move up into the main
ZTK documentation.


revno: 43
committer: Tres Seaver <tsea...@agendaless.com>
branch nick: event
timestamp: Fri 2010-04-16 20:26:20 -0400
message:
  Add docs for hacking on the package.
diff:
=== added file 'docs/hacking.rst'
--- docs/hacking.rst	1970-01-01 00:00:00 +0000
+++ docs/hacking.rst	2010-04-17 00:26:20 +0000
@@ -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.

=== modified file 'docs/index.rst'
--- docs/index.rst	2010-04-16 22:00:23 +0000
+++ docs/index.rst	2010-04-17 00:26:20 +0000
@@ -92,6 +92,7 @@
    :maxdepth: 2
 
    api
+   hacking
 
 Indices and tables
 ==================
_______________________________________________
Zope-Dev maillist  -  Zope-Dev@zope.org
https://mail.zope.org/mailman/listinfo/zope-dev
**  No cross posts or HTML encoding!  **
(Related lists - 
 https://mail.zope.org/mailman/listinfo/zope-announce
 https://mail.zope.org/mailman/listinfo/zope )

Reply via email to