[Checkins] SVN: buildout-website/trunk/source/ Fixed broken links in docs/index.rst.
Jeff Rush
jrush at taupro.com
Tue Mar 31 15:50:44 EDT 2009
Log message for revision 98724:
Fixed broken links in docs/index.rst.
Changed:
U buildout-website/trunk/source/docs/dirstruct.rst
U buildout-website/trunk/source/docs/index.rst
U buildout-website/trunk/source/index.rst
U buildout-website/trunk/source/install.rst
-=-
Modified: buildout-website/trunk/source/docs/dirstruct.rst
===================================================================
--- buildout-website/trunk/source/docs/dirstruct.rst 2009-03-31 19:48:24 UTC (rev 98723)
+++ buildout-website/trunk/source/docs/dirstruct.rst 2009-03-31 19:50:43 UTC (rev 98724)
@@ -1,11 +1,10 @@
Directory Structure of a Buildout
=================================
+.. include:: <xhtml1-special.txt>
+
.. role:: red
-.. |bullet| unicode:: U+02022
-.. include:: <xhtml1-special.txt>
-
.. sidebar:: Layout of a Buildout
.. parsed-literal::
@@ -24,88 +23,109 @@
|dagger| put :red:`red items` under version control
-.. rubric:: bootstrap.py (*version-controlled*)
+.. rubric:: bootstrap.py
-A project directory may also contain a :file:`bootstrap.py` script to help a new
-developer set up the tree after checking out a project. The file is
-optional.
+A script to be included with each project to help a new developer set up the
+tree for use with *zc.buildout* after checking out the project. It installs
+from the network the *zc.buildout* and *setuptools* packages into the project
+directory.
-It is suggested that every project that makes use of *zc.buildout* come
-bundled with a :file:`bootstrap.py` file to make it easier for the next
-developer to get started. :file:`bootstrap.py` installs the *setuptools*
-and *buildout* distributions into the project directory.
-
The actual URL for fetching the :file:`bootstrap.py` file is:
- http://svn.zope.org/*checkout*/zc.buildout/trunk/bootstrap/bootstrap.py
+ http://svn.zope.org/\*checkout\*/zc.buildout/trunk/bootstrap/bootstrap.py
-.. rubric:: buildout.cfg (*version-controlled*)
+.. rubric:: buildout.cfg
-The specification for the entire project defaults to :file:`buildout.cfg`
-but you can define others, such as :file:`deployment.cfg` and
-:file:`production.cfg`.
+Contains the default build specification for the entire project but others can
+be defined such as file:`deployment.cfg` and :file:`production.cfg`.
+Specification files can include other specification files.
-.. rubric:: .installed.cfg (*not version-controlled*)
+.. rubric:: .installed.cfg
-If you look hard, you will also find a hidden file named
-:file:`.installed.cfg`. which is where *zc.buildout* keeps its state of what
-is currently installed. Do not tamper with it.
+A hidden file that represents the current build state of the project. The
+*zc.buildout* software updates it as parts are installed or removed. The file
+is used by *zc.buildout* to compute the minimum set of changes to bring the
+project into sync with the :file:`buildout.cfg` or other specification file.
-.. rubric:: parts/ (*not version-controlled*)
+.. rubric:: parts/
-And the :file:`parts/` directory is contains code and data managed by
-*zc.buildout*, or more precisely the recipes that make it up.
+Each part may create a holding directory underneath :file:`parts/` for the
+specific use of the part's recipe. The part directory belongs to the recipe
+responsible for installing/uninstalling the part and is not intended for
+modification by the developer.
-.. rubric:: develop-eggs/ (*not version-controlled*)
+.. rubric:: develop-eggs/
-The :file:`develop-eggs/` directory holds **egg links** for software being
-developed in the buildout. The reason for separate :file:`develop-eggs/` and
-:file:`eggs/` is to allow egg cache directories to be shared across multiple
-buildouts. For example, a common developer technique is to define a common
-eggs directory in their home that all non-develop eggs are stored in. This
-allows larger buildouts to be set up much more quickly and saves disk space.
+The directory holds a kind of symlink or shortcut link to the development
+directories elsewhere on the system of distributions being worked on. The
+content of the directory is manipulated by *zc.buildout* in response to
+"develop = DIRS" entries in the build specification file.
-.. rubric:: bin/ (*not version-controlled*)
+.. rubric:: bin/
-In the :file:`bin/` directory are the executable scripts that *zc.buildout*
-generates from entrypoints within distributions.
+The directory receives executable scripts that *zc.buildout* creates from
+entrypoints defined within eggs and called out in the build specification.
-.. rubric:: bin/buildout (*not version-controlled*)
+.. rubric:: bin/buildout
+The command to invoked *zc.buildout* for bringing the state of the project
+directory into sync with a particular build specification.
-.. rubric:: bin/mypython (*not version-controlled*)
+.. rubric:: bin/mypython
-.. rubric:: eggs/ (*not version-controlled*)
+Just an example of a specific instance of a Python interpreter that
+encompasses a specific set of parts. The name is arbitrary and there can be
+any number of such custom interpreters.
-.. rubric:: downloads/ (*not version-controlled*)
+.. rubric:: eggs/
-And if you did not change the default locations of the cache directories
-for eggs and tarballs, there will be an :file:`eggs/` and may be a
-:file:`downloads/` directory. A difference between the two is that those
-in :file:`eggs/` will be referenced "in-place" while those in
-:file:`downloads/` will be unpacked into a subdirectory of :file:`parts/`.
+A cache directory of eggs pulled down from the net, ready for mapping onto the
+*sys.path* of specific parts, as given in the build specification. This
+directory may be shared across projects if configured to be in a common
+nnlocation, increasing the speed with which buildouts can be constructed.
-.. rubric:: lib/ (*not version-controlled*)
+.. rubric:: downloads/
-.. rubric:: build/ (*not version-controlled*)
+A cache directory of raw files pulled down from the net, such as compressed
+eggs, zipfiles, etc. After being downloaded into this directory, the contents
+are usually unpacked under a part name under the :file:`parts/`. This
+directory may also be shared across projects, for greater efficiency.
-.. rubric:: dist/ (*not version-controlled*)
+.. rubric:: lib/
+Not strictly part of *zc.buildout* this directory appears when running within
+a sandbox created by virtualenv. It represents a standard Python lib/
+hierarchy underwhich anything installed is outside the control of
+*zc.buildout*. It generally should be left alone.
+
+.. rubric:: build/
+
+Not strictly part of *zc.buildout* either, it is a scratch directory used by
+distutils/setuptools in the process of constructing eggs.
+
+
+.. rubric:: dist/
+
+Not strictly part of *zc.buildout*, this directory receives the final packed
+representations of distributions such as eggs ready for uploading or sharing.
+
Example::
$ cd myproject
$ svn propedit svn:ignore
+::
+
.installed.cfg
parts
develop-eggs
@@ -115,3 +135,6 @@
lib
build
dist
+
+----
+
Modified: buildout-website/trunk/source/docs/index.rst
===================================================================
--- buildout-website/trunk/source/docs/index.rst 2009-03-31 19:48:24 UTC (rev 98723)
+++ buildout-website/trunk/source/docs/index.rst 2009-03-31 19:50:43 UTC (rev 98724)
@@ -4,7 +4,7 @@
Using Buildout
--------------
-Using Buildout <using.html>`_ briefly describes the usage of
+`Using Buildout <using.html>`_ briefly describes the usage of
Buildout from the perspective of an end user or integrator.
Tutorial
@@ -23,9 +23,9 @@
List of Recipes
---------------
-A `list of the more commonly used recipes <recipelist.html>` used with Buildout.
+A `list of the more commonly used recipes <recipelist.html>`_ used with Buildout.
Links
-----
-A `collection of links related to Buildout <link.html>`.
+A `collection of links related to Buildout <link.html>`_.
Modified: buildout-website/trunk/source/index.rst
===================================================================
--- buildout-website/trunk/source/index.rst 2009-03-31 19:48:24 UTC (rev 98723)
+++ buildout-website/trunk/source/index.rst 2009-03-31 19:50:43 UTC (rev 98724)
@@ -7,6 +7,9 @@
quotes
install
docs/dirstruct
+ docs/usecase1_singlemod
+ docs/usecase2_wrapmods
+ docs/usecase3_wrapckout
docs/index
docs/links
docs/recipe
Modified: buildout-website/trunk/source/install.rst
===================================================================
--- buildout-website/trunk/source/install.rst 2009-03-31 19:48:24 UTC (rev 98723)
+++ buildout-website/trunk/source/install.rst 2009-03-31 19:50:43 UTC (rev 98724)
@@ -19,7 +19,7 @@
.. sidebar:: Don't have an ``easy_install`` command?
- The :command:`easy_install` command comes as part of the `setuptools`_
+ The :program:`easy_install` command comes as part of the `setuptools`_
package. To install it, download the :file:`ez_setup.py` file into a
temporary directory and run it with Administrator privileges.
@@ -31,7 +31,7 @@
$ easy_install zc.buildout
- This gives you a new command named :command:`buildout` to use in
+ This gives you a new command named :program:`buildout` to use in
initializing or updating a project.
.. sidebar:: For an even more isolated build environment...
@@ -48,7 +48,7 @@
$ bin/buildout init
3. To **add zc.buildout to a new project**, the primary step is to execute the
- :command:`buildout init` command while your current directory is set to the
+ :program:`buildout init` command while your current directory is set to the
root of the project directory. This command will create all necessary
files/directories, including a minimal :file:`buildout.cfg` file to control
buildout.
@@ -60,7 +60,7 @@
This command sequence will use the system Python for the project. If you
have some other project set up that uses *zc.buildout* you can borrow its
- :command:`buildout` command to initialize your new project.
+ :program:`buildout` command to initialize your new project.
::
@@ -70,7 +70,7 @@
Unfortunately this sequence of commands will not provide a
:file:`bootstrap.py` command for others to use to initialize *zc.buildout*
when they receive a copy of your project. Therefore it is recommended that
- you download and **incorporate a copy of :file:`bootstrap.py` within your
+ you download and **incorporate a copy of** :file:`bootstrap.py` **within your
project fileset**.
::
More information about the Checkins
mailing list