[Checkins] SVN: zc.buildout/branches/documentation/doc/ initial documentation skeletin
Jim Fulton
jim at zope.com
Sun Mar 13 11:33:55 EDT 2011
Log message for revision 120891:
initial documentation skeletin
Changed:
A zc.buildout/branches/documentation/doc/Makefile
A zc.buildout/branches/documentation/doc/conf.py
A zc.buildout/branches/documentation/doc/contents.rest
A zc.buildout/branches/documentation/doc/how-to-avoid-bootstrapping.rest
A zc.buildout/branches/documentation/doc/how-to-bootstrap-faster.rest
A zc.buildout/branches/documentation/doc/how-tos.rest
A zc.buildout/branches/documentation/doc/index.rest
A zc.buildout/branches/documentation/doc/make.bat
A zc.buildout/branches/documentation/doc/topics.rest
-=-
Added: zc.buildout/branches/documentation/doc/Makefile
===================================================================
--- zc.buildout/branches/documentation/doc/Makefile (rev 0)
+++ zc.buildout/branches/documentation/doc/Makefile 2011-03-13 15:33:54 UTC (rev 120891)
@@ -0,0 +1,130 @@
+# 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 singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man 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 " singlehtml to make a single large HTML file"
+ @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 " devhelp to make HTML files and a Devhelp project"
+ @echo " epub to make an epub"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " text to make text files"
+ @echo " man to make manual pages"
+ @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."
+
+singlehtml:
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+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/zcbuildout.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/zcbuildout.qhc"
+
+devhelp:
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/zcbuildout"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/zcbuildout"
+ @echo "# devhelp"
+
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through pdflatex..."
+ make -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ @echo
+ @echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ @echo
+ @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+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."
Property changes on: zc.buildout/branches/documentation/doc/Makefile
___________________________________________________________________
Added: svn:eol-style
+ native
Added: zc.buildout/branches/documentation/doc/conf.py
===================================================================
--- zc.buildout/branches/documentation/doc/conf.py (rev 0)
+++ zc.buildout/branches/documentation/doc/conf.py 2011-03-13 15:33:54 UTC (rev 120891)
@@ -0,0 +1,260 @@
+# -*- coding: utf-8 -*-
+#
+# zc.buildout documentation build configuration file, created by
+# sphinx-quickstart on Sun Feb 20 10:46:26 2011.
+#
+# 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.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# 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.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rest'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'contents'
+
+# General information about the project.
+project = u'zc.buildout'
+copyright = u'2011, Jim Fulton'
+
+# 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.5'
+# The full version, including alpha/beta/rc tags.
+release = '1.5'
+
+# 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 patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_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. See the documentation for
+# a list of builtin themes.
+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_domain_indices = 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, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = 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 = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'zcbuildoutdoc'
+
+
+# -- 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 = [
+ ('contents', 'zcbuildout.tex', u'zc.buildout Documentation',
+ u'Jim Fulton', '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
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = 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_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ ('contents', 'zcbuildout', u'zc.buildout Documentation',
+ [u'Jim Fulton'], 1)
+]
+
+
+# -- Options for Epub output ---------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = u'zc.buildout'
+epub_author = u'Jim Fulton'
+epub_publisher = u'Jim Fulton'
+epub_copyright = u'2011, Jim Fulton'
+
+# The language of the text. It defaults to the language option
+# or en if the language is not set.
+#epub_language = ''
+
+# The scheme of the identifier. Typical schemes are ISBN or URL.
+#epub_scheme = ''
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#epub_identifier = ''
+
+# A unique identification for the text.
+#epub_uid = ''
+
+# HTML files that should be inserted before the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_pre_files = []
+
+# HTML files shat should be inserted after the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_post_files = []
+
+# A list of files that should not be packed into the epub file.
+#epub_exclude_files = []
+
+# The depth of the table of contents in toc.ncx.
+#epub_tocdepth = 3
+
+# Allow duplicate toc entries.
+#epub_tocdup = True
+
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {'http://docs.python.org/': None}
Property changes on: zc.buildout/branches/documentation/doc/conf.py
___________________________________________________________________
Added: svn:keywords
+ Id
Added: svn:eol-style
+ native
Added: zc.buildout/branches/documentation/doc/contents.rest
===================================================================
--- zc.buildout/branches/documentation/doc/contents.rest (rev 0)
+++ zc.buildout/branches/documentation/doc/contents.rest 2011-03-13 15:33:54 UTC (rev 120891)
@@ -0,0 +1,23 @@
+.. zc.buildout documentation master file, created by
+ sphinx-quickstart on Sun Feb 20 10:46:26 2011.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Welcome to zc.buildout's documentation!
+=======================================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 4
+
+ index
+ how-tos
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
Property changes on: zc.buildout/branches/documentation/doc/contents.rest
___________________________________________________________________
Added: svn:eol-style
+ native
Added: zc.buildout/branches/documentation/doc/how-to-avoid-bootstrapping.rest
===================================================================
--- zc.buildout/branches/documentation/doc/how-to-avoid-bootstrapping.rest (rev 0)
+++ zc.buildout/branches/documentation/doc/how-to-avoid-bootstrapping.rest 2011-03-13 15:33:54 UTC (rev 120891)
@@ -0,0 +1,6 @@
+==========================
+How to avoid bootstrapping
+==========================
+
+Goal
+ Use buildout withou having to bother bootstrapping
Property changes on: zc.buildout/branches/documentation/doc/how-to-avoid-bootstrapping.rest
___________________________________________________________________
Added: svn:eol-style
+ native
Added: zc.buildout/branches/documentation/doc/how-to-bootstrap-faster.rest
===================================================================
--- zc.buildout/branches/documentation/doc/how-to-bootstrap-faster.rest (rev 0)
+++ zc.buildout/branches/documentation/doc/how-to-bootstrap-faster.rest 2011-03-13 15:33:54 UTC (rev 120891)
@@ -0,0 +1,8 @@
+=======================
+How to bootstrap faster
+=======================
+
+Goal
+ Create a local buildout script so you don't have to install
+ buildout somewhere else or so you get automatic updates.
+
Property changes on: zc.buildout/branches/documentation/doc/how-to-bootstrap-faster.rest
___________________________________________________________________
Added: svn:eol-style
+ native
Added: zc.buildout/branches/documentation/doc/how-tos.rest
===================================================================
--- zc.buildout/branches/documentation/doc/how-tos.rest (rev 0)
+++ zc.buildout/branches/documentation/doc/how-tos.rest 2011-03-13 15:33:54 UTC (rev 120891)
@@ -0,0 +1,30 @@
+=======
+How-tos
+=======
+
+.. toctree::
+ :maxdepth: 2
+
+ how-to-write-a-recipe-to-automate-a-task-with-python
+ how-to-play-with-some-cool-python-package
+ how-to-create-script
+ how-to-bootstrap-faster
+ how-to-avoid-bootstrapping
+ how-to-debug-the-buildout-options-database-with-annotations
+ how-to-reuse-configuration
+ how-to-use-the-same-same-options-in-all-your-buildouts
+ how-to-override-options-on-the-command-line
+ how-to-control-directory-and-file-names
+ how-to-avoid-doing-the-same-work-over-and-over
+ how-to-avoid-downloading-new-distributions
+ how-to-avoid-getting-experimental-versions-of-software
+ how-to-control-where-buildout-looks-for-distributions
+ how-to-control-where-or-if-buildut-remembers-what-in-installed
+ how-to-avoid-zipped-eggs
+ how-to-make-your-buildout-repeatable
+ how-to-write-recipes-that-download-files
+ how-to-run-setup-scripts
+ how-to-test-your-recipes
+ how-to-control-buildout-updates
+ how-to-debug-buildout-problems
+ how-to-write-recipes-that-install-distributions
Property changes on: zc.buildout/branches/documentation/doc/how-tos.rest
___________________________________________________________________
Added: svn:eol-style
+ native
Added: zc.buildout/branches/documentation/doc/index.rest
===================================================================
--- zc.buildout/branches/documentation/doc/index.rest (rev 0)
+++ zc.buildout/branches/documentation/doc/index.rest 2011-03-13 15:33:54 UTC (rev 120891)
@@ -0,0 +1,267 @@
+=========================================
+zc.buildout, an application assembly tool
+=========================================
+
+Introduction
+============
+
+zc.buildout (Buildout) was designed to help developers assemble and deploy
+applications, from simple scripts, to complex systems consisting of
+many applications, processes, and so on, working together.
+
+Buildout is similar to build tools, like, make, but it's typically
+courser grained and puts more emphasis on assembly than on building. It
+also directly supports automated disassembly as well as assembly.
+Rather than shell scripts, buildout uses Python "recipes" to define
+how things should be assembled. Python recipes often use lower level
+build tools, such a Python's distutils framework, or even make.
+
+Buildout was also designed to make it easier to work with Python
+distributions, often refereed to as eggs.
+
+Why should you care?
+--------------------
+
+- You have complex system to assemble and deploy.
+
+ Your system might have multiple application processes, sharing
+ databases and various tools that need to be configurted to work
+ together.
+
+- You want to create a Python application that uses packages not
+ included in the Python standard library.
+
+- You want to make sure that you can check your project out of a
+ version control system and get a predictable outcome when you
+ build it.
+
+- Your application needs to clean up after itself when it is
+ uninstalled. It's not enough just to install things, you need to
+ uninstall them too.
+
+Why not install what you need in Python's ``site-packages``?
+------------------------------------------------------------
+
+Python's packaging system is geared toward getting projects installed
+into Python's ``site-packages`` directory. Tools like `easy_install
+<http://packages.python.org/distribute/easy_install.html>`_
+make this even easier. The problem with installing projects this way
+is that the ``site-packages`` directory is shared by all applications
+that use a Python installation. Different applications may only work
+with or be tested with specific versions of projects. Upgrading a
+project used by one application may break others.
+
+`Virtualenv <http://pypi.python.org/pypi/virtualenv>`_ can help a lot
+by creating lightweight isolated Python environments to work in.
+
+Another reason to use Buildout is it's emphasis on repeatability
+through explicit configuration. When you install packages manually,
+even with ``easy_install``, what you end up with depends on version
+available at the time of installation. Buildout gives you a lot mnore
+control.
+
+Buildout isn't limited to Python
+--------------------------------
+
+While buildout is written in and extended with Python, it can assemble
+applifcations that have nothing to do with Python. This is useful for
+Python projects that need to leverage non-python-based tools, but
+buildout is used by projects that don't otherwise use Python.
+
+Getting Started
+===============
+
+Installation
+------------
+
+There are three basic approaches to installing buildout:
+
+Using the bootstrap script
+ A bootstrap script is a script that you can download:
+
+ http://svn.zope.org/*checkout*/zc.buildout/trunk/bootstrap/bootstrap.py
+
+ And then run to install zc.buildout in the local directory::
+
+ python bootstrap.py
+
+ The bootstrap script requires that there be a buildout
+ configuration file in the same directroy. Buildout configuration
+ files are described below.
+
+ Running the bootstrap script sets up the buildout and installs a
+ buildout script in ``bin/buildout``, which you can then run to
+ perform the buildout::
+
+ bin/buildout
+
+ Installing buildout this way doesn't affect a Python installation
+ and gives you a local buildout script. When the buildout script is
+ local, it will automatically update itself when new versions of
+ buildout are available.
+
+Using an installed buildout script
+ You can install buildout into your Python installation or
+ `virtualenv <http://pypi.python.org/pypi/virtualenv>`_ just like
+ any other project. You can then use the installed buildout script.
+
+ When buildout is installed this way, gives you a shared buildout
+ script that isn't updated automatically. To update buildout, you
+ need to install a newer version.
+
+Using a shared buildout
+ You can use any buildout script in your buildout, including one
+ installed as part of another buildout. See `How to bootstrap
+ faster`_ and `How to avoid bootstraping`_.
+
+Buildout uses a buildout configuration file to define a database of
+configuration information defining what is to be assembled. This
+database consists of a set of named dictionaries, called "sections",
+containing configuration options. One of these, the ``buildout``
+section as it defines what is to be assembled. Let's look at an
+example::
+
+ [buildout]
+ parts = zodb
+
+ [zodb]
+ recipe = zc.recipe.egg
+ eggs = ZODB3 == 3.10.2
+ interpreter = py
+
+The ``parts`` option in the ``buildout`` section defines what is to be
+assembled. In this example, we list a single part, but we could list
+as many as we want. A "part" is something we want to build as a part
+of our application. A part is defined by a section and has a "recipe"
+that defines how it is to be built and some configuration data. In
+the example above, we have a ``zodb`` part that uses the
+``zc.recipe.egg`` recipe. The recipe uses the ``eggs`` and
+``interpreter`` options.
+
+We often talk about options in sections, so for brevity, henceforth
+we'll refer to an some option in some section with the notation
+``section:option``, so, for example, we might refer to the
+``buildout:parts`` option above.
+
+The ``zc.recipe.egg`` recipe assembles given projects and their
+dependencies, builds any scripts that specify and optionally defines
+an "interpreter", which is a Python script that behaves somewhat like
+a intepreter, but which has specified projects installed.
+
+Learning more
+-------------
+
+We give some more overview information below, but overview information
+can be boring when you just want to figure out how to di
+something. You might want to skip ahead to the how-tos or consult the
+reference section.
+
+
+Terminology
+-----------
+
+project
+ A unit of functionality that is managed and distributed under a
+ name, like "django" or "dicutils". A project distritributed using
+ "distributions".
+
+distribution
+ A distribution is a packaged version of a project that is
+ distrubuted and installed locally. A project typically generates
+ many distributions for different versions and formats. The most
+ common distribution format is a "source" distribution.
+
+source distribution
+ A distribution in source form.
+
+binary distribution
+ A distribution other than a source distribution
+
+platform-dependent distribution
+ A distribution that was built in a platform-dependent way,
+ typically because it includes extension modules.
+ Platform-dependent distributions are commonly used for platforms,
+ such as Windows for which compilers typically aren't installed by
+ default. Platform-dependent distributions should generally be
+ avoided for other platforms.
+
+eggs
+ A distribution in a format, inspired by Java Jar files, which
+ requires minimal processing for installation.
+
+ In many cases, an egg can be used directly by simply incliding it's
+ path in the Python search path. Eggs may be platform dependent or
+ platform indepenent.
+
+ The term "egg" is often used sloppily to refer to any distribution
+ format. Buildout, unfortunately, often uses the term this way.
+
+ An egg may be a single file in zip format, or a directory.
+
+ Eggs are also an installation format, and Buildout alway installs
+ projects in egg format.
+
+Buildout directories
+--------------------
+
+Buildout uses a number of directories to orginize it's products. The
+names and locations of these directories can be overridden, if
+desired.
+
++-------------------------------------+--------------+-------------------------+
+| Option | Default | Descriotion |
++=====================================+==============+=========================+
+| ``buildout:directory`` | . | The root of a working |
+| | | directory in which |
+| | | Buildout is used. Other |
+| | | are relative to this |
+| | | directory by default. |
++-------------------------------------+--------------+-------------------------+
+| ``buildout:parts-directory`` | parts | A standard default |
+| | | place for recipes to |
+| | | place files they |
+| | | create. |
++-------------------------------------+--------------+-------------------------+
+| ``buildout:bin-directory`` | bin | Location for generated |
+| | | scripts. |
++-------------------------------------+--------------+-------------------------+
+| ``buildout:eggs-directory`` | eggs | Shared eggs |
++-------------------------------------+--------------+-------------------------+
+| ``buildout:develop-eggs-directory`` | develop-eggs | Non-shared eggs |
+| | | |
++-------------------------------------+--------------+-------------------------+
+
+The buildout directory defaults to the directory containing the
+buildout configuration file, which is usually a working directory for
+a software project. We often refer informally to a buildout directory
+as "a buildout".
+
+When buildout installs a Python project distribution, it normally
+creates a directory in the eggs directory. Multiple buildouts often
+use the same eggs, so the eggs directory is often shared. (See `How
+to share eggs between buildouts`_.)
+
+Sometimes, eggs can't be shared, because they're created using
+information from a particular buildout. These eggs are installed in
+the develop-eggs directory.
+
+If a part causes scripts to be installed, they're typically installed
+in the bin directory.
+
+If a part causes files to be generated, they're normally put into a
+sub-directory of the parts directory. This directory has the same
+name as the part. If a part generates a single file, it can put this
+file directly in the parts directory.
+
+XXX write more overview here.
+
+Configuration Syntax
+====================
+
+Option reuse
+------------
+
+Macros
+------
+
+
Property changes on: zc.buildout/branches/documentation/doc/index.rest
___________________________________________________________________
Added: svn:eol-style
+ native
Added: zc.buildout/branches/documentation/doc/make.bat
===================================================================
--- zc.buildout/branches/documentation/doc/make.bat (rev 0)
+++ zc.buildout/branches/documentation/doc/make.bat 2011-03-13 15:33:54 UTC (rev 120891)
@@ -0,0 +1,170 @@
+ at ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ 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. singlehtml to make a single large HTML file
+ 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. devhelp to make HTML files and a Devhelp project
+ echo. epub to make an epub
+ echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+ echo. text to make text files
+ echo. man to make manual pages
+ 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
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+ goto end
+)
+
+if "%1" == "dirhtml" (
+ %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+ goto end
+)
+
+if "%1" == "singlehtml" (
+ %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+ goto end
+)
+
+if "%1" == "pickle" (
+ %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can process the pickle files.
+ goto end
+)
+
+if "%1" == "json" (
+ %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can process the JSON files.
+ goto end
+)
+
+if "%1" == "htmlhelp" (
+ %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+ if errorlevel 1 exit /b 1
+ 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
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+ echo.^> qcollectiongenerator %BUILDDIR%\qthelp\zcbuildout.qhcp
+ echo.To view the help file:
+ echo.^> assistant -collectionFile %BUILDDIR%\qthelp\zcbuildout.ghc
+ goto end
+)
+
+if "%1" == "devhelp" (
+ %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished.
+ goto end
+)
+
+if "%1" == "epub" (
+ %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The epub file is in %BUILDDIR%/epub.
+ goto end
+)
+
+if "%1" == "latex" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "text" (
+ %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The text files are in %BUILDDIR%/text.
+ goto end
+)
+
+if "%1" == "man" (
+ %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The manual pages are in %BUILDDIR%/man.
+ goto end
+)
+
+if "%1" == "changes" (
+ %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.The overview file is in %BUILDDIR%/changes.
+ goto end
+)
+
+if "%1" == "linkcheck" (
+ %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+ if errorlevel 1 exit /b 1
+ 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
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+ goto end
+)
+
+:end
Property changes on: zc.buildout/branches/documentation/doc/make.bat
___________________________________________________________________
Added: svn:eol-style
+ native
Added: zc.buildout/branches/documentation/doc/topics.rest
===================================================================
--- zc.buildout/branches/documentation/doc/topics.rest (rev 0)
+++ zc.buildout/branches/documentation/doc/topics.rest 2011-03-13 15:33:54 UTC (rev 120891)
@@ -0,0 +1,8 @@
+=======
+Topics
+=======
+
+.. toctree::
+ :maxdepth: 2
+
+ extensions
Property changes on: zc.buildout/branches/documentation/doc/topics.rest
___________________________________________________________________
Added: svn:eol-style
+ native
More information about the checkins
mailing list