[Checkins] SVN: Sandbox/jens/zmi.core/trunk/ - move brainstoring results into Sphinx documentation
Jens Vagelpohl
jens at dataflake.org
Wed Nov 16 11:37:25 UTC 2011
Log message for revision 123375:
- move brainstoring results into Sphinx documentation
- added Todo list as part of the Sphinx documentation
- add a simple docs building script to the buildout
Changed:
U Sandbox/jens/zmi.core/trunk/README.txt
U Sandbox/jens/zmi.core/trunk/buildout.cfg
_U Sandbox/jens/zmi.core/trunk/docs/
U Sandbox/jens/zmi.core/trunk/docs/conf.py
U Sandbox/jens/zmi.core/trunk/docs/hacking.rst
U Sandbox/jens/zmi.core/trunk/docs/index.rst
A Sandbox/jens/zmi.core/trunk/docs/thoughts.rst
A Sandbox/jens/zmi.core/trunk/docs/todo.rst
D Sandbox/jens/zmi.core/trunk/src/zmi/core/browser/database/todo.txt
-=-
Modified: Sandbox/jens/zmi.core/trunk/README.txt
===================================================================
--- Sandbox/jens/zmi.core/trunk/README.txt 2011-11-16 11:22:43 UTC (rev 123374)
+++ Sandbox/jens/zmi.core/trunk/README.txt 2011-11-16 11:37:25 UTC (rev 123375)
@@ -1,7 +1,8 @@
-``zmi.core`` README
-=====================
+==============
+ ``zmi.core``
+==============
The ``zmi.core`` package provides core components for the new
-Zope ZMI, based on content from the older Zope 2 ZMI.
+Zope ZMI, based on content from the older Zope 2 Zope Management
+Interface (ZMI).
-Please see ``doc/index.rst`` for the documentation.
Modified: Sandbox/jens/zmi.core/trunk/buildout.cfg
===================================================================
--- Sandbox/jens/zmi.core/trunk/buildout.cfg 2011-11-16 11:22:43 UTC (rev 123374)
+++ Sandbox/jens/zmi.core/trunk/buildout.cfg 2011-11-16 11:37:25 UTC (rev 123375)
@@ -1,6 +1,6 @@
[buildout]
develop = .
-parts = test sphinx scripts zopepy instance
+parts = test sphinx docs scripts zopepy instance
extends =
http://svn.zope.org/repos/main/zopetoolkit/trunk/zopeapp-sources.cfg
http://svn.zope.org/repos/main/Zope/trunk/sources.cfg
@@ -42,3 +42,16 @@
debug-mode = on
verbose-security = on
http-address = 127.0.0.1:8080
+
+[docs]
+recipe = collective.recipe.template
+input = inline:
+ #!/bin/sh
+ # Build the Sphinx documentation in one step
+ export PATH="${buildout:bin-directory}:$PATH"
+ cd "${buildout:directory}/docs"
+ make clean
+ make html
+output = ${buildout:bin-directory}/docs
+mode = 755
+
Property changes on: Sandbox/jens/zmi.core/trunk/docs
___________________________________________________________________
Added: svn:ignore
+ _build
Modified: Sandbox/jens/zmi.core/trunk/docs/conf.py
===================================================================
--- Sandbox/jens/zmi.core/trunk/docs/conf.py 2011-11-16 11:22:43 UTC (rev 123374)
+++ Sandbox/jens/zmi.core/trunk/docs/conf.py 2011-11-16 11:37:25 UTC (rev 123375)
@@ -52,7 +52,7 @@
# built documents.
#
# The short X.Y version.
-version = '%s.%s' % tuple(map(int, rqmt.version.split('.')[:2]))
+version = '.'.join(rqmt.version.split('.')[:2])
# The full version, including alpha/beta/rc tags.
release = rqmt.version
Modified: Sandbox/jens/zmi.core/trunk/docs/hacking.rst
===================================================================
--- Sandbox/jens/zmi.core/trunk/docs/hacking.rst 2011-11-16 11:22:43 UTC (rev 123374)
+++ Sandbox/jens/zmi.core/trunk/docs/hacking.rst 2011-11-16 11:37:25 UTC (rev 123375)
@@ -16,18 +16,7 @@
$ svn checkout svn://svn.zope.org/repos/main/zmi.core/trunk zmi.core
-The project also mirrors the trunk from the Subversion repository as a
-Bazaar branch on Launchpad:
-https://code.launchpad.net/zmi.core
-
-You can branch the trunk from there using Bazaar:
-
-.. code-block:: sh
-
- $ bzr branch lp:zmi.core
-
-
Running the tests in a ``virtualenv``
-------------------------------------
@@ -127,33 +116,7 @@
Build finished. The HTML pages are in _build/html.
-You can also test the code snippets in the documentation:
-.. code-block:: sh
-
- $ PATH=/tmp/hack-zmi.core/bin:$PATH make doctest
- sphinx-build -b doctest -d _build/doctrees . _build/doctest
- ...
- running tests...
-
- Document: index
- ---------------
- 1 items passed all tests:
- 17 tests in default
- 17 tests in 1 items.
- 17 passed and 0 failed.
- Test passed.
-
- Doctest summary
- ===============
- 17 tests
- 0 failures in tests
- 0 failures in setup code
- build succeeded.
- Testing of doctests in the sources finished, look at the \
- results in _build/doctest/output.txt.
-
-
Running the tests using :mod:`zc.buildout`
-------------------------------------------
@@ -187,30 +150,11 @@
---------------------------------------------------
The :mod:`zmi.core` buildout installs the Sphinx scripts required to build
-the documentation, including testing its code snippets:
+the documentation:
.. code-block:: sh
- $ cd docs
- $ PATH=../bin:$PATH make doctest html
- .../bin/sphinx-build -b doctest -d .../docs/_build/doctrees .../docs .../docs/_build/doctest
- running tests...
-
- Document: index
- ---------------
- 1 items passed all tests:
- 17 tests in default
- 17 tests in 1 items.
- 17 passed and 0 failed.
- Test passed.
-
- Doctest summary
- ===============
- 17 tests
- 0 failures in tests
- 0 failures in setup code
- build succeeded.
- Testing of doctests in the sources finished, look at the results in .../docs/_build/doctest/output.txt.
+ $ ./bin/docs
.../bin/sphinx-build -b html -d .../docs/_build/doctrees .../docs .../docs/_build/html
...
build succeeded.
@@ -249,13 +193,3 @@
You can then upload that patch file as an attachment to a Launchpad bug
report.
-If you branched the code from Launchpad using Bazaar, you have another
-option: you can "push" your branch to Launchpad:
-
-.. code-block:: sh
-
- $ bzr push lp:~tseaver/zmi.core/cool_feature
-
-After pushing your branch, you can link it to a bug report on Launchpad,
-or request that the maintainers merge your branch using the Launchpad
-"merge request" feature.
Modified: Sandbox/jens/zmi.core/trunk/docs/index.rst
===================================================================
--- Sandbox/jens/zmi.core/trunk/docs/index.rst 2011-11-16 11:22:43 UTC (rev 123374)
+++ Sandbox/jens/zmi.core/trunk/docs/index.rst 2011-11-16 11:37:25 UTC (rev 123375)
@@ -1,17 +1,27 @@
-:mod:`zmi.core` Documentation
-==============================
+.. include:: ../README.txt
-This package contains core ZMI components and views.
-Contents:
+Narrative documentation
+=======================
.. toctree::
:maxdepth: 2
+ thoughts
usage
- api
hacking
+ todo
+
+API documentation
+=================
+
+.. toctree::
+ :maxdepth: 2
+
+ api
+
+
Indices and tables
==================
Added: Sandbox/jens/zmi.core/trunk/docs/thoughts.rst
===================================================================
--- Sandbox/jens/zmi.core/trunk/docs/thoughts.rst (rev 0)
+++ Sandbox/jens/zmi.core/trunk/docs/thoughts.rst 2011-11-16 11:37:25 UTC (rev 123375)
@@ -0,0 +1,173 @@
+Thoughts for a Zope 4 ZMI
+=========================
+
+Assumptions and scope
+---------------------
+The following points are not meant as exact definitions, they are more
+of a brain dump and starting point:
+
+* The ZMI is meant to support administering and developing Zope
+ applications, especially server-side debugging and introspection.
+
+* The ZMI is not meant as a generic UI for administering applications
+ or entering/editing data in an application.
+
+* Request debugging by interception of application requests is not a
+ goal, but the ZMI can support integration of such tools.
+
+* Day to day application administration tasks should never be dependent
+ on having the new ZMI around. Applications must remain usable without it.
+
+* The ZMI must always function when needed, even if an application's own
+ views are broken.
+
+* The ZMI is not meant to provide full backwards compatibility with
+ the old Zope 2 ZMI.
+
+
+Use cases, functions and desirable views
+----------------------------------------
+* ZODB (Caches, Connections, ...)
+
+* ZODB browsing (selection of attributes, readability, "broken" objects).
+ This needs UI TLC to become/stay usable, and documentation of underlying
+ concepts and goals to enable future development
+
+* ZODB history
+
+* ZODB transaction log
+
+* relational databases (SQLAlchemy, ZSQL),
+
+* Zope process parameters
+
+* Other configuration parameters (read and experiment with them)
+
+* interactive interpreter (e.g. to set attributes, including transaction
+ integration)
+
+* profiler
+
+* Zope 3 components without their own UI (generations, registry
+ introspection, etc)
+
+* code browser??
+
+* PropertyManager or alternatives?
+
+* error log (Zope Site Error Log)
+
+* long request log
+
+* offline support (dumping configurations, parameter, etc)
+
+* single request debugging (request logs with complete request/response
+ information, performance stats, profiling, other code logging output,
+ post-mortem debugging (like WebError). This can potentially be extended
+ by application-specific debugging information. This kind of debugging
+ should be enabled from the ZMI and singe request overlay mechanisms
+ should be available alongside a central UI.
+
+* content adding is application-specific. The question what support
+ to offer from the ZMI is not solved.
+
+
+Unsupported use cases
+---------------------
+* generic CRUD/BREAD
+
+
+Non-functional requirements
+---------------------------
+* The ZMI should be resilient in the face of application issues ("broken"
+ objects, application errors, missing filesystem code)
+
+* simple code
+
+* generic UI (like SmallTalk), but no attempt at "one size fits all" like
+ Plone
+
+* easy pluggability for additional ZMI views
+
+* separation of UI and code to ease refactoring of DTML-dependent code
+
+* as little dependencies as possible beyond the Zope egg and its dependencies
+
+
+Implementation thoughts
+-----------------------
+* minimal boilerplate: O-Wrap, Tree, menu system?
+
+* separate skin (++skin++zmi)
+
+* generic object traversal independent of URL space and application code
+
+* the views should have as few dependencies (e.g. form library
+ dependencies) as possible. It should run without requiring extra
+ installation or configuration steps past installing the egg and
+ calling up the views.
+
+* translations are supported by wrapping user-visible messages as
+ TranslationStrings in a shard translation domain ("zmi").
+
+
+Starting points
+---------------
+* current Zope 2 ZMI views
+
+* methods in Zope or add-on products that support the old ZMI
+
+* plone.app.debugtoolbar / pyramid toolbar
+
+* Smalltalk UI
+
+
+Current ZMI views brainstorming
+-------------------------------
+* It's not clear how to convert the "Add list" in the old ZMI. The new
+ ZMI may have to provide a way to register "addable" items.
+
+* The "Contents" tab is application-specific. Its replacement is a
+ more generic object browser.
+
+* It's not clear how to handle "virtual" items that don't really exist in
+ the database, such as the ''/temp_folder''
+
+* The "View" tab is useful for developers, they can jump to the public
+ view for an object.
+
+* The PropertyManager "Properties" tab is an older Zope 2 API with an
+ unclear future status. Most developers have moved to store attributes
+ in a different way, meaning their owbjects provide built-in views
+ for them already.
+
+* The "Security" tab will continue to be available as a "read only" view
+ to show a security profile for the given context. It should retain the
+ current functionality of allowing user name input to show rights for
+ specific user accounts for the given context.
+
+* The "Undo" tab will remain; having some ZODB transaction log is already
+ in scope for the new ZMI.
+
+* The "Security" tab replacement can also take over what the "Owner" tab
+ does now, meaning it should the "executable" owner as well.
+
+* The "Interfaces" tab will remain but lose the ability to add marker
+ interfaces for an object which is an application-specific setting.
+ Only the application knows what such interfaces mean.
+
+* The "Find" tab should become part of the object browser.
+
+* "Edit" tabs are application-specific, they must be provided by the
+ applicaton developer.
+
+* The "Proxy" tab for setting proxy roles on an object will not be
+ supported.
+
+* "History" is an application-specific tab, so it's not part of the
+ core package.
+
+* Nearly all views from the Control_Panel should be reimplemented as
+ part of a new ZMI.
+
+
Added: Sandbox/jens/zmi.core/trunk/docs/todo.rst
===================================================================
--- Sandbox/jens/zmi.core/trunk/docs/todo.rst (rev 0)
+++ Sandbox/jens/zmi.core/trunk/docs/todo.rst 2011-11-16 11:37:25 UTC (rev 123375)
@@ -0,0 +1,14 @@
+To do list
+==========
+This list does not claim to be a complete representation. It is a simple
+memory aid and the place where the correlation between old Zope 2 ZMI
+views and their templates is documented.
+
+Zope.App.ApplicationManager
+---------------------------
+
+| [ ] manage_main (dtml/dbMain)
+| [ ] manage_activity (dtml/activity)
+| [ ] manage_cacheParameters (dtml/manage_cacheParameters)
+| [ ] manage_cacheGC (dtml/cacheGC)
+| [ ] manage_setHistoryLength (?)
Deleted: Sandbox/jens/zmi.core/trunk/src/zmi/core/browser/database/todo.txt
===================================================================
--- Sandbox/jens/zmi.core/trunk/src/zmi/core/browser/database/todo.txt 2011-11-16 11:22:43 UTC (rev 123374)
+++ Sandbox/jens/zmi.core/trunk/src/zmi/core/browser/database/todo.txt 2011-11-16 11:37:25 UTC (rev 123375)
@@ -1,8 +0,0 @@
-Source views
-
-Zope.App.ApplicationManager
-"manage_main" = dtml/dbMain
-"manage_activity" = dtml/activity
-"manage_cacheParameters" = dtml/manage_cacheParameters
-"manage_cacheGC" = dtml/cacheGC
-"manage_setHistoryLength" = ?
\ No newline at end of file
More information about the checkins
mailing list