lazr-developers team mailing list archive

[Gary Poster <gary.poster@xxxxxxxxxxxxx>]

OK, Barry and I agreed on a position yesterday evening (see https://dev.launchpad.net/LazrStyleGuide).  I have also been naughty and made a few other unrelated changes, because I am hopeful that this will be the last time I touch lazr.yourpkg in a while.

- I made .bzrignore ignore *.egg-info.  This makes it easier to copy the file wholesale into legacy packages, which has been convenient.

- I switched the tests to use the name ``additional_tests``.  This means that the setuptools testrunner can easily find them, and I configured the Zope testrunner to find them.

- I added a ./bin/docs command that will generate Sphinx docs from the package.  This uses the package README.txt.  I used this to test that our plan to have a top-level README.txt and docs directories should work, but it is also a useful tool, so I left it in.

- I removed the "or later" from the license statement, per Francis' comment.

- I converted the doc test finder to use pkg_resources.

- I removed basics.txt, putting the content in README.txt.

Gary

=== modified file '.bzrignore'
--- .bzrignore	2009-03-14 00:08:24 +0000
+++ .bzrignore	2009-03-16 22:49:35 +0000
@@ -3,7 +3,7 @@
 .installed.cfg
 develop-eggs
 parts
-src/lazr.yourpkg.egg-info
+*.egg-info
 tags
 TAGS
 build

=== modified file 'buildout.cfg'
--- buildout.cfg	2009-01-08 18:44:42 +0000
+++ buildout.cfg	2009-03-17 13:06:55 +0000
@@ -2,6 +2,7 @@
 parts =
     interpreter
     test
+    docs
     tags
 unzip = true
 
@@ -10,11 +11,18 @@
 [test]
 recipe = zc.recipe.testrunner
 eggs = lazr.yourpkg
-defaults = '--tests-pattern ^tests --exit-with-status'.split()
+defaults = '--tests-pattern ^tests --exit-with-status --suite-name additional_tests'.split()
+
+[docs]
+recipe = z3c.recipe.sphinxdoc
+eggs = lazr.yourpkg [docs]
+index-doc = README
+default.css =
+layout.html =
 
 [interpreter]
 recipe = zc.recipe.egg
-interpreter=py
+interpreter = py
 eggs = lazr.yourpkg
        docutils
 

=== modified file 'setup.py'
--- setup.py	2009-03-16 16:24:05 +0000
+++ setup.py	2009-03-17 15:23:45 +0000
@@ -55,7 +55,7 @@
     long_description=generate(
         'src/lazr/yourpkg/README.txt',
         'src/lazr/yourpkg/NEWS.txt'),
-    license='LGPL v3 or later',
+    license='LGPL v3',
     install_requires=[
         'setuptools',
         'zope.interface',
@@ -68,6 +68,10 @@
         "License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)",
         "Operating System :: OS Independent",
         "Programming Language :: Python"],
-    setup_requires=['eggtestinfo'],
-    test_suite='lazr.yourpkg.tests.test_suite',
+    extras_require=dict(
+        docs=['Sphinx',
+              'z3c.recipe.sphinxdoc']
+    ),
+    setup_requires=['eggtestinfo', 'setuptools_bzr'],
+    test_suite='lazr.yourpkg.tests',
     )

=== modified file 'src/lazr/yourpkg/README.txt'
--- src/lazr/yourpkg/README.txt	2009-01-10 01:00:49 +0000
+++ src/lazr/yourpkg/README.txt	2009-03-17 15:17:14 +0000
@@ -15,8 +15,31 @@
     along with lazr.yourpkg.  If not, see <http://www.gnu.org/licenses/>.
 
 LAZR yourpkg
-***********
-
-This is a pure template for new lazr namespace packages.  Whenever you want to
-make a new lazr subpackage, just branch this code and change all occurrences
-of 'yourpkg' with whatever your subpackage's name is.
+************
+
+This is a pure template for new lazr namespace packages.  
+
+Please see https://dev.launchpad.net/LazrStyleGuide and
+https://dev.launchpad.net/Hacking for how to develop in this
+package.
+
+This is an example Sphinx_ `Table of contents`_.  If you add files to the docs
+directory, you should probably improve it.
+
+.. toctree::
+   :glob:
+
+   *   
+   docs/*
+
+.. _Sphinx: http://sphinx.pocoo.org/
+.. _Table of contents: http://sphinx.pocoo.org/concepts.html#the-toc-tree
+
+Importable
+==========
+
+The lazr.yourpkg package is importable, and has a version number.
+
+    >>> import lazr.yourpkg
+    >>> print 'VERSION:', lazr.yourpkg.__version__
+    VERSION: ...
\ No newline at end of file

=== removed file 'src/lazr/yourpkg/docs/basic.txt'
--- src/lazr/yourpkg/docs/basic.txt	2009-01-09 02:10:26 +0000
+++ src/lazr/yourpkg/docs/basic.txt	1970-01-01 00:00:00 +0000
@@ -1,8 +0,0 @@
-Importable
-==========
-
-The lazr.yourpkg package is importable, and has a version number.
-
-    >>> import lazr.yourpkg
-    >>> print 'VERSION:', lazr.yourpkg.__version__
-    VERSION: ...

=== added directory 'src/lazr/yourpkg/tests'
=== added file 'src/lazr/yourpkg/tests/__init__.py'
--- src/lazr/yourpkg/tests/__init__.py	1970-01-01 00:00:00 +0000
+++ src/lazr/yourpkg/tests/__init__.py	2009-03-16 22:47:59 +0000
@@ -0,0 +1,16 @@
+# Copyright 2009 Canonical Ltd.  All rights reserved.
+#
+# This file is part of lazr.yourpkg
+#
+# lazr.yourpkg is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# lazr.yourpkg is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with lazr.yourpkg.  If not, see <http://www.gnu.org/licenses/>.

=== renamed file 'src/lazr/yourpkg/tests.py' => 'src/lazr/yourpkg/tests/test_docs.py'
--- src/lazr/yourpkg/tests.py	2009-03-13 21:51:39 +0000
+++ src/lazr/yourpkg/tests/test_docs.py	2009-03-17 00:43:59 +0000
@@ -4,11 +4,13 @@
 
 __metaclass__ = type
 __all__ = [
-    'test_suite',
+    'additional_tests',
     ]
 
+import atexit
+import doctest
 import os
-import doctest
+import pkg_resources
 import unittest
 
 DOCTEST_FLAGS = (
@@ -17,16 +19,18 @@
     doctest.REPORT_NDIFF)
 
 
-def test_suite():
-    package_directory = os.path.dirname(__file__)
-    docs_directory = os.path.normpath(os.path.join(package_directory, 'docs'))
-    if os.path.exists(docs_directory):
-        doctest_files = [os.path.join('docs', filename)
-                         for filename in os.listdir(docs_directory)
-                         if filename.endswith('.txt')]
-    else:
-        doctest_files = []
-    doctest_files.append('README.txt')
-    kwargs = dict(module_relative=True, optionflags=DOCTEST_FLAGS)
+def additional_tests():
+    doctest_files = [
+        os.path.abspath(
+            pkg_resources.resource_filename('lazr.yourpkg', 'README.txt'))]
+    if pkg_resources.resource_exists('lazr.yourpkg', 'docs'):
+        for name in pkg_resources.resource_listdir('lazr.yourpkg', 'docs'):
+            if name.endswith('.txt'):
+                doctest_files.append(
+                    os.path.abspath(
+                        pkg_resources.resource_filename(
+                            'lazr.yourpkg', 'docs/%s' % name)))
+    kwargs = dict(module_relative=False, optionflags=DOCTEST_FLAGS)
+    atexit.register(pkg_resources.cleanup_resources)
     return unittest.TestSuite((
         doctest.DocFileSuite(*doctest_files, **kwargs)))


-- 
https://code.edge.launchpad.net/~gary/lazr.yourpkg/trunk/+merge/4477
Your team LAZR Developers is subscribed to branch lp:lazr.yourpkg.