[Checkins] SVN: martian/trunk/ Update documentation before release.
Martijn Faassen
faassen at infrae.com
Fri Jun 6 12:07:05 EDT 2008
Log message for revision 87204:
Update documentation before release.
Changed:
U martian/trunk/CHANGES.txt
U martian/trunk/README.txt
U martian/trunk/setup.py
U martian/trunk/src/martian/README.txt
-=-
Modified: martian/trunk/CHANGES.txt
===================================================================
--- martian/trunk/CHANGES.txt 2008-06-06 15:38:21 UTC (rev 87203)
+++ martian/trunk/CHANGES.txt 2008-06-06 16:07:04 UTC (rev 87204)
@@ -1,7 +1,7 @@
CHANGES
*******
-0.10 (unreleased)
+0.10 (2008-06-06)
=================
Feature changes
Modified: martian/trunk/README.txt
===================================================================
--- martian/trunk/README.txt 2008-06-06 15:38:21 UTC (rev 87203)
+++ martian/trunk/README.txt 2008-06-06 16:07:04 UTC (rev 87204)
@@ -2,45 +2,4 @@
Martian
*******
-"There was so much to grok, so little to grok from." -- Stranger in a
-Strange Land, by Robert A. Heinlein
-
-Martian provides infrastructure for declarative configuration of
-Python code. Martian is especially useful for the construction of
-frameworks that need to provide a flexible plugin infrastructure.
-
-Why is this package named ``martian``? In the novel "Stranger in a
-Strange Land", the verb *grok* is introduced:
-
- Grok means to understand so thoroughly that the observer becomes a
- part of the observed -- to merge, blend, intermarry, lose identity
- in group experience.
-
-In the context of this package, "grokking" stands for the process of
-deducing declarative configuration actions from Python code. In the
-novel, grokking is originally a concept that comes from the planet
-Mars. Martians *grok*. Since this package helps you grok code, it's
-called Martian.
-
-Martian provides a framework that allows configuration to be expressed
-in declarative Python code. These declarations can often be deduced
-from the structure of the code itself. The idea is to make these
-declarations so minimal and easy to read that even extensive
-configuration does not overly burden the programmers working with the
-code. Configuration actions are executed during a separate phase
-("grok time"), not at import time, which makes it easier to reason
-about and easier to test.
-
-The ``martian`` package is a spin-off from the `Grok project`_, in the
-context of which this codebase was first developed. While Grok uses
-it, the code is completely independent of Grok.
-
-For more information about using Martian, see:
-
-* ``src/martian/README.txt``
-
-* ``src/martian/directive.txt``
-
-* ``src/martian/scan.txt``
-
-.. _`Grok project`: http://grok.zope.org
+A library to grok configuration from Python code.
Modified: martian/trunk/setup.py
===================================================================
--- martian/trunk/setup.py 2008-06-06 15:38:21 UTC (rev 87203)
+++ martian/trunk/setup.py 2008-06-06 16:07:04 UTC (rev 87204)
@@ -7,13 +7,10 @@
long_description = (
read('README.txt')
+ '\n' +
- read('CHANGES.txt')
- + '\n' +
- 'Detailed Documentation\n'
- '**********************\n'
- + '\n' +
read('src', 'martian', 'README.txt')
+ '\n' +
+ read('CHANGES.txt')
+ + '\n' +
'Download\n'
'********\n'
)
Modified: martian/trunk/src/martian/README.txt
===================================================================
--- martian/trunk/src/martian/README.txt 2008-06-06 15:38:21 UTC (rev 87203)
+++ martian/trunk/src/martian/README.txt 2008-06-06 16:07:04 UTC (rev 87204)
@@ -1,17 +1,20 @@
-Martian
-=======
+Martian tutorial
+****************
+Introduction
+============
+
"There was so much to grok, so little to grok from." -- Stranger in a
Strange Land, by Robert A. Heinlein
Martian provides infrastructure for declarative configuration of
Python code. Martian is especially useful for the construction of
frameworks that need to provide a flexible plugin
-infrastructure. Martian doesn't actually provide any infrastructure
-for plugin registries and such. Many frameworks have their own, and if
-you need a generic one, you might want to consider
-``zope.component``. Martian just allows you to make the registration
-of such plugins less verbose.
+infrastructure. Martian doesn't actually provide infrastructure for
+plugin registries (except for itself). Many frameworks have their own
+systems for this, and if you need a generic one, you might want to
+consider ``zope.component``. Martian just allows you to make the
+registration of plugins less verbose.
You can see Martian as doing something that you can also solve with
metaclasses, with the following advantages:
@@ -41,6 +44,13 @@
Mars. Martians *grok*. Since this package helps you grok code, it's
called Martian.
+Martian provides a framework that allows configuration to be expressed
+in declarative Python code. These declarations can often be deduced
+from the structure of the code itself. The idea is to make these
+declarations so minimal and easy to read that even extensive
+configuration does not overly burden the programmers working with the
+code.
+
The ``martian`` package is a spin-off from the `Grok project`_, in the
context of which this codebase was first developed. While Grok uses
it, the code is completely independent of Grok.
@@ -48,7 +58,7 @@
.. _`Grok project`: http://grok.zope.org
Motivation
-----------
+==========
"Deducing declarative configuration actions from Python code" - that
sounds very abstract. What does it actually mean? What is
@@ -192,7 +202,7 @@
easier to test.
Configuration the Martian Way
------------------------------
+=============================
Let's now transform the above ``templating`` module and the
``sillytemplating`` module to use Martian. First we must recognize
@@ -360,7 +370,7 @@
well. In this way Martian can use itself to extend itself.
Grokking instances
-------------------
+==================
Above we've seen how you can grok classes. Martian also supplies a way
to grok instances. This is less common in typical frameworks, and has
@@ -411,8 +421,8 @@
('lion', <Animal object at ...>)]
More information
-----------------
+================
For many more details and examples of more kinds of grokkers, please
-see ``core.txt``. For more information on directives see
-``directive.txt``.
+see ``src/martian/core.txt``. For more information on directives see
+``src/martian/directive.txt``.
More information about the Checkins
mailing list