[Checkins] SVN: z3c.recipe.sphinxdoc/trunk/ begin preparing
z3c.recipe.sphinxdoc for a first release.
Paul Carduner
paulcarduner at gmail.com
Sun May 11 00:51:59 EDT 2008
Log message for revision 86642:
begin preparing z3c.recipe.sphinxdoc for a first release.
Changed:
_U z3c.recipe.sphinxdoc/trunk/
U z3c.recipe.sphinxdoc/trunk/README.txt
U z3c.recipe.sphinxdoc/trunk/bootstrap.py
U z3c.recipe.sphinxdoc/trunk/buildout.cfg
U z3c.recipe.sphinxdoc/trunk/src/z3c/recipe/sphinxdoc/__init__.py
A z3c.recipe.sphinxdoc/trunk/src/z3c/recipe/sphinxdoc/index.txt
-=-
Property changes on: z3c.recipe.sphinxdoc/trunk
___________________________________________________________________
Name: svn:ignore
+ bin
develop-eggs
parts
Modified: z3c.recipe.sphinxdoc/trunk/README.txt
===================================================================
--- z3c.recipe.sphinxdoc/trunk/README.txt 2008-05-11 04:29:53 UTC (rev 86641)
+++ z3c.recipe.sphinxdoc/trunk/README.txt 2008-05-11 04:51:58 UTC (rev 86642)
@@ -1,9 +1 @@
-z3c.recipe.sphinxdoc
-====================
-
-Introduction
-------------
-
-How to use this recipe
-----------------------
-
+See src/z3c/recipe/sphinxdoc/index.txt for more information.
\ No newline at end of file
Modified: z3c.recipe.sphinxdoc/trunk/bootstrap.py
===================================================================
--- z3c.recipe.sphinxdoc/trunk/bootstrap.py 2008-05-11 04:29:53 UTC (rev 86641)
+++ z3c.recipe.sphinxdoc/trunk/bootstrap.py 2008-05-11 04:51:58 UTC (rev 86642)
@@ -1,6 +1,6 @@
##############################################################################
#
-# Copyright (c) 2006 Zope Corporation and Contributors.
+# Copyright (c) 2007 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
@@ -17,108 +17,36 @@
The script accepts buildout command-line options, so you can
use the -c option to specify an alternate configuration file.
+$Id$
"""
+
import os, shutil, sys, tempfile, urllib2
-join = os.path.join
-py_version = 'python%s.%s' % (sys.version_info[0], sys.version_info[1])
+tmpeggs = tempfile.mkdtemp()
-def mkdir(path):
- if not os.path.exists(path):
- print 'Creating %s' % path
- os.makedirs(path)
+ez = {}
+exec urllib2.urlopen('http://peak.telecommunity.com/dist/ez_setup.py'
+ ).read() in ez
+ez['use_setuptools'](to_dir=tmpeggs, download_delay=0)
-def symlink(src, dest):
- if not os.path.exists(dest):
- os.symlink(src, dest)
- else:
- print 'Symlink %s already exists' % dest
+import pkg_resources
+cmd = 'from setuptools.command.easy_install import main; main()'
+if sys.platform == 'win32':
+ cmd = '"%s"' % cmd # work around spawn lamosity on windows
-def rmtree(dir):
- if os.path.exists(dir):
- print 'Deleting tree %s' % dir
- shutil.rmtree(dir)
+ws = pkg_resources.working_set
+assert os.spawnle(
+ os.P_WAIT, sys.executable, sys.executable,
+ '-c', cmd, '-mqNxd', tmpeggs, 'zc.buildout',
+ dict(os.environ,
+ PYTHONPATH=
+ ws.find(pkg_resources.Requirement.parse('setuptools')).location
+ ),
+ ) == 0
-def make_exe(fn):
- if os.name == 'posix':
- oldmode = os.stat(fn).st_mode & 07777
- newmode = (oldmode | 0555) & 07777
- os.chmod(fn, newmode)
-
-def make_virtual_python():
- if os.name != 'posix':
- print "This script only works on Unix-like platforms, sorry."
- return
-
- lib_dir = join('python', 'lib', py_version)
- inc_dir = join('python', 'include', py_version)
- bin_dir = join('python', 'bin')
-
- if sys.executable.startswith(bin_dir):
- print 'Please use the *system* python to run this script'
- return
-
- mkdir('python')
- prefix = sys.prefix
- mkdir(lib_dir)
- stdlib_dir = join(prefix, 'lib', py_version)
- for fn in os.listdir(stdlib_dir):
- if fn != 'site-packages':
- symlink(join(stdlib_dir, fn), join(lib_dir, fn))
-
- mkdir(join(lib_dir, 'site-packages'))
-
- mkdir(inc_dir)
- stdinc_dir = join(prefix, 'include', py_version)
- for fn in os.listdir(stdinc_dir):
- symlink(join(stdinc_dir, fn), join(inc_dir, fn))
-
- if sys.exec_prefix != sys.prefix:
- exec_dir = join(sys.exec_prefix, 'lib', py_version)
- for fn in os.listdir(exec_dir):
- symlink(join(exec_dir, fn), join(lib_dir, fn))
-
- mkdir(bin_dir)
- print 'Copying %s to %s' % (sys.executable, bin_dir)
- py_executable = join(bin_dir, 'python')
- if sys.executable != py_executable:
- shutil.copyfile(sys.executable, py_executable)
- make_exe(py_executable)
-
-
-if __name__ == "__main__":
- if sys.executable != os.path.abspath('python/bin/python'):
- make_virtual_python()
- sys.exit(os.spawnve(
- os.P_WAIT, 'python/bin/python',
- ['python/bin/python'] + sys.argv, os.environ))
-
- tmpeggs = tempfile.mkdtemp()
-
- ez = {}
- exec urllib2.urlopen('http://peak.telecommunity.com/dist/ez_setup.py'
- ).read() in ez
- ez['use_setuptools'](to_dir=tmpeggs, download_delay=0)
-
- import pkg_resources
-
- cmd = 'from setuptools.command.easy_install import main; main()'
- if sys.platform == 'win32':
- cmd = '"%s"' % cmd # work around spawn lamosity on windows
-
- ws = pkg_resources.working_set
- assert os.spawnle(
- os.P_WAIT, sys.executable, sys.executable,
- '-c', cmd, '-mqNxd', tmpeggs, 'zc.buildout',
- dict(os.environ,
- PYTHONPATH=
- ws.find(pkg_resources.Requirement.parse('setuptools')).location
- ),
- ) == 0
-
- ws.add_entry(tmpeggs)
- ws.require('zc.buildout')
- import zc.buildout.buildout
- zc.buildout.buildout.main(sys.argv[1:] + ['bootstrap'])
- shutil.rmtree(tmpeggs)
+ws.add_entry(tmpeggs)
+ws.require('zc.buildout')
+import zc.buildout.buildout
+zc.buildout.buildout.main(sys.argv[1:] + ['bootstrap'])
+shutil.rmtree(tmpeggs)
Modified: z3c.recipe.sphinxdoc/trunk/buildout.cfg
===================================================================
--- z3c.recipe.sphinxdoc/trunk/buildout.cfg 2008-05-11 04:29:53 UTC (rev 86641)
+++ z3c.recipe.sphinxdoc/trunk/buildout.cfg 2008-05-11 04:51:58 UTC (rev 86642)
@@ -1,15 +1,7 @@
[buildout]
-index = http://download.zope.org/zope3.4
develop = .
-parts = z3c.recipe.tag test
-newest = false
+parts = docs
-[z3c.recipe.tag]
-recipe = zc.recipe.egg
-unzip = true
-eggs = z3c.recipe.tag
-
-[test]
-recipe = zc.recipe.testrunner
-eggs = z3c.recipe.tag
-defaults = ['--exit-with-status', '--tests-pattern', '^f?tests$', '-v']
+[docs]
+recipe = z3c.recipe.sphinxdoc
+eggs = z3c.recipe.sphinxdoc
\ No newline at end of file
Modified: z3c.recipe.sphinxdoc/trunk/src/z3c/recipe/sphinxdoc/__init__.py
===================================================================
--- z3c.recipe.sphinxdoc/trunk/src/z3c/recipe/sphinxdoc/__init__.py 2008-05-11 04:29:53 UTC (rev 86641)
+++ z3c.recipe.sphinxdoc/trunk/src/z3c/recipe/sphinxdoc/__init__.py 2008-05-11 04:51:58 UTC (rev 86642)
@@ -16,6 +16,7 @@
import os
import os.path
from os.path import join, dirname
+from email import parser
import logging
import shutil
@@ -60,6 +61,8 @@
if not os.path.isdir(installDir):
os.mkdir(installDir)
+ srcDirs = eval(self.options.get('src-dirs','{}'))
+
projectsData = {}
#for each egg listed as a buildout option, create a configuration space.
for doc in docs:
@@ -88,14 +91,15 @@
join(templatesDir, 'layout.html'))
installed.append(join(templatesDir, 'layout.html'))
+ metadata = dict(parser.Parser().parsestr('\n'.join(doc._get_metadata('PKG-INFO'))).items())
#create conf.py
confPyPath = join(partDir, 'conf.py')
confPy = open(confPyPath, 'w')
- confPy.write(confPyTemplate % dict(project=doc.project_name,
- copyright='some copyright',
- version=doc._version,
- release=doc._version,
+ confPy.write(confPyTemplate % dict(project=metadata.get('Name', doc.project_name),
+ copyright=metadata.get('Author', 'Zope Community'),
+ version=metadata.get('Version', doc.version),
+ release=metadata.get('Version', doc.version),
staticDir=staticDir,
templatesDir=templatesDir,
indexDoc=self.options.get('index-doc','index')
@@ -108,7 +112,10 @@
if not os.path.isdir(buildDir):
os.mkdir(buildDir)
- srcDir = os.path.join(doc.location, self.options.get('src-dir',''))
+ srcDir = os.path.join(doc.location,
+ srcDirs.get(doc.project_name,
+ self.options.get('src-dir',
+ doc.project_name.replace('.','/'))))
projectsData[doc.project_name] = ['-q','-c',partDir,
srcDir, buildDir]
Added: z3c.recipe.sphinxdoc/trunk/src/z3c/recipe/sphinxdoc/index.txt
===================================================================
--- z3c.recipe.sphinxdoc/trunk/src/z3c/recipe/sphinxdoc/index.txt (rev 0)
+++ z3c.recipe.sphinxdoc/trunk/src/z3c/recipe/sphinxdoc/index.txt 2008-05-11 04:51:58 UTC (rev 86642)
@@ -0,0 +1,78 @@
+z3c.recipe.sphinxdoc
+====================
+
+Introduction
+------------
+
+This buildout recipe aids in the generation of documentation for the
+zope.org website from restructured text files located in a package.
+It uses Sphinx to build static html files which can stand alone as a
+very nice looking website.
+
+Usage Instructions
+------------------
+
+Suppose you have a package called ``z3c.form``. In the ``setup.py``
+for ``z3c.form`` it is recommended that you add a ``docs`` section
+to the extras_require argument. It should look something like this:
+
+.. code-block:: python
+
+ extras_require = dict(
+ docs = ['Sphinx',
+ 'z3c.recipe.sphinxdoc']
+ )
+
+Then in the buildout.cfg file for your package, add a ``docs`` section
+that looks like this::
+
+ [docs]
+ recipe = z3c.recipe.sphinxdoc
+ eggs = z3c.form [docs]
+
+Be sure to include it in the parts, as in::
+
+ [buildout]
+ develop = .
+ parts = docs
+
+Now you can rerun buildout. The recipe will have created an
+executable script in the bin directory called ``docs``.
+
+This script will run the Sphinx documentation generation tool on your
+source code. By default, it expects there to be an ``index.txt`` file
+in the source code. In this case, ``index.txt`` would have to be in
+``src/z3c/form/index.txt``. This file can be a standard restructured
+text file, and can use all the sphinx goodies. For example, your
+``index.txt`` might look like this::
+
+ Welcome to z3c.form's documentation!
+ ====================================
+
+ Contents:
+
+ .. toctree::
+ :maxdepth: 2
+
+ README
+
+ Indices and tables
+ ==================
+
+ * :ref:`genindex`
+ * :ref:`modindex`
+ * :ref:`search`
+
+You should read the documentation for Sphinx to learn more about it.
+It is available here: http://sphinx.pocoo.org/
+
+Now you should be able to run the ``docs`` script::
+
+ $ ./bin/docs
+
+This generates all the documentation for you and placed it in the
+parts directory. You can then open it up in firefox and take a look::
+
+ $ firefox parts/docs/z3c.form/build/index.html
+
+And that's it!
\ No newline at end of file
Property changes on: z3c.recipe.sphinxdoc/trunk/src/z3c/recipe/sphinxdoc/index.txt
___________________________________________________________________
Name: svn:eol-style
+ native
More information about the Checkins
mailing list