-----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 [email protected] 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 <[email protected]> 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 <[email protected]> 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 <[email protected]> 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 <[email protected]> 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 <[email protected]> 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='[email protected]', 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 <[email protected]> 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 <[email protected]> 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 - [email protected] 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 )
