[Checkins] SVN: buildout-website/trunk/source/ Intermediate check-in; includes final installation page and preliminary
Jeff Rush
jrush at taupro.com
Mon Mar 30 20:03:30 EDT 2009
Log message for revision 98663:
Intermediate check-in; includes final installation page and preliminary
dirstruct page.
Changed:
U buildout-website/trunk/source/_static/default.css
A buildout-website/trunk/source/docs/dirstruct.rst
U buildout-website/trunk/source/glossary.rst
U buildout-website/trunk/source/index.rst
U buildout-website/trunk/source/install.rst
-=-
Modified: buildout-website/trunk/source/_static/default.css
===================================================================
--- buildout-website/trunk/source/_static/default.css 2009-03-30 23:54:15 UTC (rev 98662)
+++ buildout-website/trunk/source/_static/default.css 2009-03-31 00:03:30 UTC (rev 98663)
@@ -269,3 +269,29 @@
border: 4px solid red !important;
}
+
+/* AVAILABLE-COLORS
+ * The set of colors understood by docutils.
+ */
+
+.maroon { color: maroon; }
+.red { color: red; }
+.magenta { color: magenta; }
+.fuchsia { color: fuchsia; }
+.pink { color: #FAA; }
+.orange { color: orange; }
+.yellow { color: yellow; }
+.lime { color: lime; }
+.green { color: green; }
+.olive { color: olive; }
+.teal { color: teal; }
+.cyan { color: cyan; }
+.aqua { color: aqua; }
+.blue { color: blue; }
+.navy { color: navy; }
+.purple { color: purple; }
+.black { color: black; }
+.gray { color: gray; }
+.silver { color: silver; }
+.white { color: white; }
+
Added: buildout-website/trunk/source/docs/dirstruct.rst
===================================================================
--- buildout-website/trunk/source/docs/dirstruct.rst (rev 0)
+++ buildout-website/trunk/source/docs/dirstruct.rst 2009-03-31 00:03:30 UTC (rev 98663)
@@ -0,0 +1,117 @@
+Directory Structure of a Buildout
+=================================
+
+.. role:: red
+.. |bullet| unicode:: U+02022
+
+.. include:: <xhtml1-special.txt>
+
+.. sidebar:: Layout of a Buildout
+
+ .. parsed-literal::
+
+ project/
+ :red:`bootstrap.py` |dagger|
+ :red:`buildout.cfg` |dagger|
+ .installed.cfg
+ parts/
+ develop-eggs/
+ bin/
+ buildout
+ mypython
+ eggs/
+ downloads/
+
+ |dagger| put :red:`red items` under version control
+
+.. rubric:: bootstrap.py (*version-controlled*)
+
+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.
+
+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
+
+
+.. rubric:: buildout.cfg (*version-controlled*)
+
+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`.
+
+
+.. rubric:: .installed.cfg (*not version-controlled*)
+
+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.
+
+
+.. rubric:: parts/ (*not version-controlled*)
+
+And the :file:`parts/` directory is contains code and data managed by
+*zc.buildout*, or more precisely the recipes that make it up.
+
+
+.. rubric:: develop-eggs/ (*not version-controlled*)
+
+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.
+
+
+.. rubric:: bin/ (*not version-controlled*)
+
+In the :file:`bin/` directory are the executable scripts that *zc.buildout*
+generates from entrypoints within distributions.
+
+
+.. rubric:: bin/buildout (*not version-controlled*)
+
+
+.. rubric:: bin/mypython (*not version-controlled*)
+
+
+.. rubric:: eggs/ (*not version-controlled*)
+
+
+.. rubric:: downloads/ (*not version-controlled*)
+
+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/`.
+
+
+.. rubric:: lib/ (*not version-controlled*)
+
+.. rubric:: build/ (*not version-controlled*)
+
+.. rubric:: dist/ (*not version-controlled*)
+
+
+Example::
+
+ $ cd myproject
+ $ svn propedit svn:ignore
+
+ .installed.cfg
+ parts
+ develop-eggs
+ bin
+ eggs
+ downloads
+ lib
+ build
+ dist
Property changes on: buildout-website/trunk/source/docs/dirstruct.rst
___________________________________________________________________
Added: svn:mime-type
+ text/plain
Added: svn:keywords
+ Author Date Id Revision
Added: svn:eol-style
+ native
Modified: buildout-website/trunk/source/glossary.rst
===================================================================
--- buildout-website/trunk/source/glossary.rst 2009-03-30 23:54:15 UTC (rev 98662)
+++ buildout-website/trunk/source/glossary.rst 2009-03-31 00:03:30 UTC (rev 98663)
@@ -4,30 +4,16 @@
========
.. glossary::
+ :sorted:
- builder
- A class (inheriting from :class:`~sphinx.builder.Builder`) that takes
- parsed documents and performs an action on them. Normally, builders
- translate the documents to an output format, but it is also possible to
- use the builder builders that e.g. check for broken links in the
- documentation, or build coverage information.
+ buildout
+ ???
- configuration directory
- The directory containing :file:`conf.py`. By default, this is the same
- as the :term:`source directory`, but can be set differently with the
- **-c** command-line option.
+ egg
+ ???
- description unit
- The basic building block of Sphinx documentation. Every "description
- directive" creates such a unit; and most units can be cross-referenced
- to.
+ part
+ ???
- environment
- A structure where information about all documents under the root is
- saved, and used for cross-referencing. The environment is pickled after
- the parsing stage, so that successive runs only need to read and parse
- new and changed documents.
-
- source directory
- The directory which, including its subdirectories, contains all source
- files for one Sphinx project.
+ recipe
+ ???
Modified: buildout-website/trunk/source/index.rst
===================================================================
--- buildout-website/trunk/source/index.rst 2009-03-30 23:54:15 UTC (rev 98662)
+++ buildout-website/trunk/source/index.rst 2009-03-31 00:03:30 UTC (rev 98663)
@@ -1,11 +1,3 @@
-.. Buildout documentation master file, created by sphinx-quickstart on
- Tue Apr 29 11:06:32 2008. You can adapt this file completely to
- your liking, but it should at least contain the root `toctree`
- directive.
-
- Q: To whom should the copyright for the website be assigned?
- A: Zope Foundation or Jim Fulton --baiju
-
Buildout - system for managing development buildouts
====================================================
@@ -13,7 +5,7 @@
screencasts
install
- dirstruct
+ docs/dirstruct
docs/index
docs/links
docs/recipe
@@ -22,6 +14,7 @@
docs/using
community
glossary
+ thanks
What is Buildout?
-----------------
Modified: buildout-website/trunk/source/install.rst
===================================================================
--- buildout-website/trunk/source/install.rst 2009-03-30 23:54:15 UTC (rev 98662)
+++ buildout-website/trunk/source/install.rst 2009-03-31 00:03:30 UTC (rev 98663)
@@ -6,11 +6,11 @@
eggs.
1. Many **existing projects** are already based on *zc.buildout* and include
- within their project files the necessary ``bootstrap.py`` file. To
+ within their project files the necessary :file:`bootstrap.py` file. To
activate use of *zc.buildout* within such a project, simply run that
- ``bootstrap.py`` using the specific Python interpreter for the project.
+ :file:`bootstrap.py` using the specific Python interpreter for the project.
This may be the system Python or in the case of a `virtualenv`_ sandbox,
- the Python within the ``bin/`` subdirectory of the project.
+ the Python within the :file:`bin/` subdirectory of the project.
::
@@ -19,9 +19,9 @@
.. sidebar:: Don't have an ``easy_install`` command?
- The ``easy_install`` command comes as part of the `setuptools`_ package. To
- install it, download the `ez_setup.py`_ file into a temporary directory and
- run it with Administrator privileges.
+ The :command:`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.
2. While *zc.buildout* is most often installed within each project directory,
it can also be **installed system-wide**, to make it easy to create new
@@ -31,14 +31,14 @@
$ easy_install zc.buildout
- This gives you a new command named ``buildout`` to use in initializing or
- updating a project.
+ This gives you a new command named :command:`buildout` to use in
+ initializing or updating a project.
.. sidebar:: For an even more isolated build environment...
To use an isolated instance of Python within the project, the following
- commands will create a new sandbox and establish use of *buildout* within
- it.
+ commands will create a new sandbox and establish use of *zc.buildout*
+ within it.
::
@@ -48,9 +48,9 @@
$ bin/buildout init
3. To **add zc.buildout to a new project**, the primary step is to execute the
- "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 ``buildout.cfg`` file to control
+ :command:`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,25 +60,31 @@
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
- ``buildout`` command to initialize your new project.
+ :command:`buildout` command to initialize your new project.
::
$ cd newproject
$ /oldproject/bin/buildout init
- Unfortunately this sequence of commands will not provide a ``bootstrap.py``
- command for others to use to initialize *buildout* when they receive a copy
- of your project. Therefore it is recommended that you download and
- **incorporate a copy of ``bootstrap.py`` within your project fileset**.
+ 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
+ project fileset**.
::
$ cd newproject
$ wget http://svn.zope.org/*checkout*/zc.buildout/trunk/bootstrap/bootstrap.py
+----
+A good next step in understanding *zc.buildout* is :doc:`docs/dirstruct` which
+also covers which file/directories should be under version control and which
+should not.
+
.. _`ez_setup.py`: http://peak.telecommunity.com/dist/ez_setup.py
.. _`bootstrap.py`: http://svn.zope.org/*checkout*/zc.buildout/trunk/bootstrap/bootstrap.py
.. _`zc.buildout`: http://pypi.python.org/pypi/zc.buildout
More information about the Checkins
mailing list