[svn r64029] * move test docs into their own subdir

* don't use sphinx for now, put the support code to attic
* remove some old docs

--HG--
branch : trunk

doc/Makefile

@@ -1,94 +0,0 @@
-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-PAPER         =
-
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help clean html 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 "  htmlall   to force make all 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 _build/*
-
-html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html
-	@echo
-	@echo "Build finished. The HTML pages are in _build/html."
-
-htmlall:
-	$(SPHINXBUILD) -a -b html $(ALLSPHINXOPTS) _build/html
-	@echo
-	@echo "Build finished. The HTML pages are in _build/html."
-
-dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) _build/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in _build/dirhtml."
-
-pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) _build/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in _build/htmlhelp."
-
-qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) _build/qthelp
-	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in _build/qthelp, like this:"
-	@echo "# qcollectiongenerator _build/qthelp/py lib.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile _build/qthelp/py lib.qhc"
-
-latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in _build/latex."
-	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
-	      "run these through (pdf)latex."
-
-changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes
-	@echo
-	@echo "The overview file is in _build/changes."
-
-linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in _build/linkcheck/output.txt."
-
-doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) _build/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in _build/doctest/output.txt."

doc/__init__.py

@@ -1 +0,0 @@
-#

doc/_templates/pylib/theme.conf

@@ -1,9 +0,0 @@
-[theme]
-inherit = default
-stylesheet = style.css
-pygments_style = sphinx
-
-[options]
-rightsidebar = false
-stickysidebar = false
-

doc/bin.txt

@@ -15,7 +15,7 @@ available on your command prompt.
 The ``py.test`` executable is the main entry point into the py-lib testing tool,
 see the `py.test documentation`_.
 
-.. _`py.test documentation`: test.html
+.. _`py.test documentation`: test/test.html
 
 ``py.cleanup``
 ==============

doc/coding-style.txt

@@ -1,65 +0,0 @@
-=====================================================
-Coding Style for the Py lib and friendly applications 
-=====================================================
-
-
-Honour PEP 8: Style Guide for Python Code
------------------------------------------ 
-
-First of all, if you haven't already read it, read the `PEP 8
-Style Guide for Python Code`_ which, if in doubt, serves as
-the default coding-style for the py lib. 
-
-Documentation and Testing 
--------------------------
-
-- generally we want to drive and interweave coding of
-  documentation, tests and real code as much as possible. 
-  Without good documentation others may never know about
-  your latest and greatest feature. 
-
-naming 
-------
-
-- directories, modules and namespaces are always **lowercase**
-
-- classes and especially Exceptions are most often **CamelCase**
-
-- types, i.e. very widely usable classes like the ``py.path`` 
-  family are all lower case. 
-
-- never use plural names in directory and file names
-
-- functions/methods are lowercase and ``_`` - separated if
-  you really need to separate at all
-
-- it's appreciated if you manage to name files in a directory
-  so that tab-completion on the shell level is as easy as possible. 
-
-
-committing
-----------
-
-- adding features requires adding appropriate tests. 
-
-- bug fixes should be encoded in a test before being fixed. 
-
-- write telling log messages because several people
-  will read your diffs, and we plan to have a search facility 
-  over the py lib's subversion repository. 
-
-- if you add ``.txt`` or ``.py`` files to the repository then 
-  please make sure you have ``svn:eol-style`` set to native. 
-  which allows checkin/checkout in native line-ending format.
-
-Miscellaneous 
--------------
-
-- Tests are the insurance that your code will be maintained 
-  further and survives major releases. 
-
-- Try to put the tests close to the tested code, don't
-  overload directories with names. 
-
-.. _`PEP 8 Style Guide for Python Code`: http://www.python.org/peps/pep-0008.html
-.. _`py-dev mailing list`: http://codespeak.net/mailman/listinfo/py-dev 

doc/conf.py

@@ -1,195 +0,0 @@
-# -*- coding: utf-8 -*-
-#
-# py lib documentation build configuration file, created by
-# sphinx-quickstart on Wed Apr  1 19:13:13 2009.
-#
-# 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('.'))
-
-# -- 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', 'roles']
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix of source filenames.
-source_suffix = '.txt'
-
-# The encoding of source files.
-#source_encoding = 'utf-8'
-
-# The master toctree document.
-master_doc = 'index'
-
-# General information about the project.
-project = u'py lib'
-copyright = u'2009, Holger Krekel and others'
-
-# 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 = '1.0'
-# The full version, including alpha/beta/rc tags.
-release = '1.0.0b1'
-
-# 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 = 'pylib'
-
-# 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 = ['_templates']
-
-# 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 = "img/pylib.png"
-
-# 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 = False
-
-# 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 = 'pylibdoc'
-
-
-# -- 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', 'pylib.tex', u'py lib Documentation',
-   u'Holger Krekel', '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

doc/confrest.py

@@ -22,6 +22,9 @@ class Page(object):
         self._root = html.html(self.head, self.body) 
         self.fill() 
 
+    def a_href(self, name, url):
+        return html.a(name, class_="menu", href=url)
+
     def a_docref(self, name, relhtmlpath):
         docpath = self.project.docpath
         return html.a(name, class_="menu",
@@ -39,6 +42,8 @@ class Page(object):
             self.a_docref("index", "index.html"),
             #self.a_apigenref("api", "api/index.html"),
             #self.a_apigenref("source", "source/index.html"),
+            #self.a_href("source", "http://bitbucket.org/hpk42/py-trunk/src/"),
+            self.a_href("issues", "http://bitbucket.org/hpk42/py-trunk/issues/"),
             self.a_docref("contact", "contact.html"),
             self.a_docref("download", "download.html"),
         ]

doc/conftest.py

@@ -1,3 +1,5 @@
 #XXX make work: excludedirs = ['_build']
+import py
+py.test.importorskip("pygments")
 pytest_plugins = ['pytest_restdoc']
 rsyncdirs = ['.']

doc/contact.txt

@@ -32,7 +32,6 @@ Contact and communication
     or the mailing list and ask questions, get involved. 
 
 .. _FOAF: http://en.wikipedia.org/wiki/FOAF
-.. _`coding style`: coding-style.html 
 .. _us: http://codespeak.net/mailman/listinfo/py-dev
 .. _codespeak: http://codespeak.net/
 .. _`py-dev`: 

doc/index.txt

@@ -30,7 +30,7 @@ Minor support functionality
 .. _`py.io`: io.html
 .. _`py.path`: path.html
 .. _`py.code`: code.html
-.. _`py.test`: test.html 
+.. _`py.test`: test/test.html 
 .. _`py lib scripts`: bin.html
 .. _`py.xml`: xml.html 
 .. _`miscellaneous features`: misc.html 

doc/make.bat

@@ -1,112 +0,0 @@
-@ECHO OFF
-
-REM Command file for Sphinx documentation
-
-set SPHINXBUILD=sphinx-build
-set ALLSPHINXOPTS=-d _build/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 (_build\*) do rmdir /q /s %%i
-	del /q /s _build\*
-	goto end
-)
-
-if "%1" == "html" (
-	%SPHINXBUILD% -b html %ALLSPHINXOPTS% _build/html
-	echo.
-	echo.Build finished. The HTML pages are in _build/html.
-	goto end
-)
-
-if "%1" == "dirhtml" (
-	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% _build/dirhtml
-	echo.
-	echo.Build finished. The HTML pages are in _build/dirhtml.
-	goto end
-)
-
-if "%1" == "pickle" (
-	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% _build/pickle
-	echo.
-	echo.Build finished; now you can process the pickle files.
-	goto end
-)
-
-if "%1" == "json" (
-	%SPHINXBUILD% -b json %ALLSPHINXOPTS% _build/json
-	echo.
-	echo.Build finished; now you can process the JSON files.
-	goto end
-)
-
-if "%1" == "htmlhelp" (
-	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% _build/htmlhelp
-	echo.
-	echo.Build finished; now you can run HTML Help Workshop with the ^
-.hhp project file in _build/htmlhelp.
-	goto end
-)
-
-if "%1" == "qthelp" (
-	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% _build/qthelp
-	echo.
-	echo.Build finished; now you can run "qcollectiongenerator" with the ^
-.qhcp project file in _build/qthelp, like this:
-	echo.^> qcollectiongenerator _build\qthelp\py lib.qhcp
-	echo.To view the help file:
-	echo.^> assistant -collectionFile _build\qthelp\py lib.ghc
-	goto end
-)
-
-if "%1" == "latex" (
-	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% _build/latex
-	echo.
-	echo.Build finished; the LaTeX files are in _build/latex.
-	goto end
-)
-
-if "%1" == "changes" (
-	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% _build/changes
-	echo.
-	echo.The overview file is in _build/changes.
-	goto end
-)
-
-if "%1" == "linkcheck" (
-	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% _build/linkcheck
-	echo.
-	echo.Link check complete; look for any errors in the above output ^
-or in _build/linkcheck/output.txt.
-	goto end
-)
-
-if "%1" == "doctest" (
-	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% _build/doctest
-	echo.
-	echo.Testing of doctests in the sources finished, look at the ^
-results in _build/doctest/output.txt.
-	goto end
-)
-
-:end

doc/roles.py

@@ -1,5 +0,0 @@
-from docutils.nodes import literal
-
-def setup(app):
-    app.add_generic_role('api', literal)
-    app.add_generic_role('source', literal)

doc/test/attic.txt

@@ -46,7 +46,7 @@ useful for calling application test machinery with different
 parameter sets but counting each of the calls as a separate
 tests. 
 
-.. _`generative tests`: test-features.html#generative-tests
+.. _`generative tests`: features.html#generative-tests
 
 The other extension possibility is about 
 specifying a custom test ``Item`` class which 

doc/test/dist.txt

@@ -93,10 +93,10 @@ platforms - and report back failures from all platforms
 at once.   The provided specifications strings 
 use the `xspec syntax`_. 
 
-.. _`xspec syntax`: execnet.html#xspec
+.. _`xspec syntax`: ../execnet.html#xspec
 
 .. _`socketserver.py`: http://codespeak.net/svn/py/dist/py/execnet/script/socketserver.py
-.. _`py.execnet`: execnet.html
+.. _`py.execnet`: ../execnet.html
 
 Specifying test exec environments in a conftest.py
 -------------------------------------------------------------

doc/test/ext.txt

@@ -110,11 +110,4 @@ name.  Given a filesystem ``fspath`` it is constructed as follows:
 Plugin hooks and events  
 =======================================
 
-.. automodule:: py.__.test.plugin.api
+XXX
-
-.. autoclass:: PluginHooks
-    :members:
-
-.. autoclass:: Events
-    :members:
-

doc/test/features.txt

@@ -1,18 +1,26 @@
 ==================================================
-Features
+py.test Features
 ==================================================
 
-py.test is a standalone-tool that collects and runs tests for
+py.test is an extensible tool for running all kinds
-your Python application and modules.  py.test works across
+of tests one one or more machines.  It supports a variety
-linux, windows and osx and on Python 2.3 - Python 2.6.
+of testing methods for your Python application and modules,
+including unit, functional, integration and doc-testing. 
 
-It aims to support *unit-tests* and *functional tests* written
+It is used in projects that run more than 10000 tests 
-in Python and is used in projects that run more than 10000
+daily as well as single-python-module projects. 
-tests regularly.  
 
 py.test presents a clean and powerful command line interface
 and strives to generally make testing a fun effort. 
 
+py.test 1.0 works across linux, windows and osx 
+and on Python 2.3 - Python 2.6.
+
+More detailed feature list: 
+
+.. contents::
+    :depth: 1
+
 automatically collects and executes tests 
 ===============================================
 
@@ -23,7 +31,13 @@ From each test module every function with a leading ``test_``
 or class with a leading ``Test`` name is collected.  
 
 .. _`generative tests`: 
-.. _`collection process`: test-ext.html#collection-process
+.. _`collection process`: ext.html#collection-process
+
+Rapidly write integration, functional, unit tests 
+===================================================
+
+py.test provides 
+
 
 load-balance tests to multiple CPUs
 ===================================
@@ -35,7 +49,7 @@ tests to multiple CPUs by issuing for example::
 
 Read more on `distributed testing`_. 
 
-.. _`distributed testing`: test-dist.html
+.. _`distributed testing`: dist.html
 
 Distribute tests across machines
 ===================================
@@ -47,7 +61,7 @@ platforms one a single test run`. Ad-hoc
 means that there are **no installation 
 requirements whatsoever** on the remote side. 
 
-.. _`ad-hoc run your test on multiple platforms one a single test run`: test-dist.html#atonce
+.. _`ad-hoc run your test on multiple platforms one a single test run`: dist.html#atonce
 
 extensive debugging support 
 ===================================
@@ -270,7 +284,7 @@ for these purposes:
 * running non-python tests
 * managing test state setup 
 
-.. _`py.test plugins`: test-plugins.html
+.. _`py.test plugins`: plugins.html
 
 .. _`reStructured Text`: http://docutils.sourceforge.net
 .. _`Python debugger`: http://docs.python.org/lib/module-pdb.html

doc/test/quickstart.txt

@@ -53,7 +53,7 @@ Python test module is inspected for test methods starting with ``test_``.
 Please refer to `features`_ for a walk through the basic features. 
 
 
-.. _download: download.html
+.. _download: ../download.html
-.. _features: test-features.html
+.. _features: features.html
 
 

doc/test/test.txt

@@ -5,7 +5,7 @@ py.test
 * rapidly collect and run tests 
 * use unit- or doctests, functional or integration tests 
 * distribute tests to multiple environments
-* local or global plugins for custom test types
+* local or global plugins for custom test scenarios and types
 
 quickstart_: for getting started immediately.
 
@@ -17,24 +17,10 @@ extend_: writing plugins and advanced configuration.
 
 `distributed testing`_ how to distribute test runs to other machines and platforms. 
 
-.. _quickstart: test-quickstart.html
+.. _quickstart: quickstart.html
-.. _features: test-features.html
+.. _features: features.html
-.. _plugins: test-plugins.html
+.. _plugins: plugins.html
-.. _extend: test-ext.html
+.. _extend: ext.html
-.. _`distributed testing`: test-dist.html
+.. _`distributed testing`: dist.html
 
 
-Contents:
-
-.. toctree::
-   :maxdepth: 2
-
-   test-quickstart
-   test-features
-   test-plugins
-   test-ext
-   test-dist
-   test-config
-   test-statemanage
-   test-examples
-   impl-test

doc/xml.txt

@@ -166,4 +166,4 @@ complete the probably request-specific serialization of
 your Tags.  Hum, it's probably harder to explain this than to
 actually code it :-) 
 
-.. _`py.test`: test.html
+.. _`py.test`: test/test.html