[Zope3-checkins] SVN: Zope3/trunk/src/zope/app/apidoc/ Dressed up
the API docs, ZCML in particular.
Shane Hathaway
shane at zope.com
Sat Nov 13 18:21:48 EST 2004
Log message for revision 28451:
Dressed up the API docs, ZCML in particular.
- Colored the section headers
- Moved the ZCML directive description to the top of the page
- Ordered schema fields by required first, then alphabetically. This is
a more natural order for documentation readers than the
inheritance and definition order. The inheritance and definition order
looks arbitrary to anyone who has not stared at the source code.
- Used an asterisk to indicate required fields
Changed:
U Zope3/trunk/src/zope/app/apidoc/browser/apidoc.css
U Zope3/trunk/src/zope/app/apidoc/ifacemodule/browser.py
U Zope3/trunk/src/zope/app/apidoc/ifacemodule/index.pt
U Zope3/trunk/src/zope/app/apidoc/servicemodule/index.pt
U Zope3/trunk/src/zope/app/apidoc/utilitymodule/index.pt
U Zope3/trunk/src/zope/app/apidoc/zcmlmodule/browser.py
U Zope3/trunk/src/zope/app/apidoc/zcmlmodule/index.pt
-=-
Modified: Zope3/trunk/src/zope/app/apidoc/browser/apidoc.css
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/browser/apidoc.css 2004-11-13 21:05:19 UTC (rev 28450)
+++ Zope3/trunk/src/zope/app/apidoc/browser/apidoc.css 2004-11-13 23:21:47 UTC (rev 28451)
@@ -55,13 +55,23 @@
margin-top: 0;
}
+div.details-subheader {
+ font-size: 125%;
+ font-weight: normal;
+ margin-top: 0;
+}
+
h2.details-section {
font-size: 150%;
font-style: italic;
+ background-color: #ccf;
+ padding: 2px 0.5em 2px 0.5em;
}
h3.details-section {
margin-bottom: 2pt;
+ background-color: #ccf;
+ padding: 2px 0.5em 2px 0.5em;
}
p.breadcrumbs {
@@ -166,4 +176,11 @@
code.zcml .objectref {
color: DarkSalmon;
-}
\ No newline at end of file
+}
+
+b.required {
+ color: red;
+}
+
+b.optional {
+}
Modified: Zope3/trunk/src/zope/app/apidoc/ifacemodule/browser.py
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/ifacemodule/browser.py 2004-11-13 21:05:19 UTC (rev 28450)
+++ Zope3/trunk/src/zope/app/apidoc/ifacemodule/browser.py 2004-11-13 23:21:47 UTC (rev 28451)
@@ -186,8 +186,8 @@
'path': getPythonPath(class_).replace('.', '/')}
-def _getRequired(field):
- """Return a string representation of whether the field is required.
+def _getRequiredCSS(field):
+ """Return a CSS class name that represents whether the field is required.
Examples::
@@ -195,17 +195,17 @@
... required = False
>>> field = Field()
- >>> _getRequired(field)
- u'optional'
+ >>> _getRequiredCSS(field)
+ 'optional'
>>> field.required = True
- >>> _getRequired(field)
- u'required'
+ >>> _getRequiredCSS(field)
+ 'required'
"""
if field.required:
- return _('required')
+ return 'required'
else:
- return _('optional')
+ return 'optional'
def _getRealFactory(factory):
@@ -360,8 +360,11 @@
for method in _get(self.context, IMethod).values()]
def getFields(self):
- r"""Return a list of fields in the order they were specified.
+ r"""Return a list of fields in required + alphabetical order.
+ The required attributes are listed first, then the optional
+ attributes.
+
Example::
>>> from zope.app.apidoc.tests import pprint
@@ -379,7 +382,8 @@
[('id', 'zope.schema.interfaces.ITextLine'),
('name', 'ITextLine')]),
('name', 'title'),
- ('required', u'required')],
+ ('required', True),
+ ('required_css', 'required')],
[('class',
[('name', 'Text'),
('path', 'zope/schema/_bootstrapfields/Text')]),
@@ -388,17 +392,23 @@
('iface',
[('id', 'zope.schema.interfaces.IText'), ('name', 'IText')]),
('name', 'description'),
- ('required', u'optional')]]
+ ('required', False),
+ ('required_css', 'optional')]]
"""
# The `Interface` class have no security declarations, so that we are
# not able to access any API methods on proxied objects. If we only
# remove security proxies, the location proxy's module will be
# returned.
- fields = map(lambda x: x[1], _getInOrder(self.context, IField))
+ _itemsorter = lambda x, y: cmp(
+ (x[1].required and '1' or '2', x[0].lower()),
+ (y[1].required and '1' or '2', y[0].lower()))
+ fields = map(lambda x: x[1], _getInOrder(
+ self.context, IField, _itemsorter=_itemsorter))
return [{'name': self._getFieldName(field),
'iface': _getFieldInterface(field),
'class': _getFieldClass(field),
- 'required': _getRequired(field),
+ 'required': field.required,
+ 'required_css': _getRequiredCSS(field),
'default': repr(field.default),
'description': renderText(
field.description or '',
Modified: Zope3/trunk/src/zope/app/apidoc/ifacemodule/index.pt
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/ifacemodule/index.pt 2004-11-13 21:05:19 UTC (rev 28450)
+++ Zope3/trunk/src/zope/app/apidoc/ifacemodule/index.pt 2004-11-13 23:21:47 UTC (rev 28451)
@@ -61,14 +61,16 @@
</li>
<li tal:repeat="field fields">
- <b><code tal:content="field/name">field</code></b>
+ <b tal:attributes="class field/required_css">
+ <code tal:content="field/name">field</code>
+ <span tal:condition="field/required">*</span>
+ </b>
- <a href=""
tal:attributes="
href string:../../Class/${field/class/path}/index.html">
<code tal:content="field/class/name">Field</code></a>
- (<span tal:content="string:${field/required}, ">optional, </span>
- <span i18n:translate="">default</span> =
- <code tal:content="field/default" />)<br>
+ (<span i18n:translate="">default</span> =
+ <code tal:content="field/default" />)<br />
<span tal:content="structure field/description">field desc</span>
</li>
@@ -285,5 +287,10 @@
</div>
</div>
+ <p>
+ <em><b class="required">*</b> =
+ <span i18n:translate="">required</span></em>
+ </p>
+
</body>
</html>
Modified: Zope3/trunk/src/zope/app/apidoc/servicemodule/index.pt
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/servicemodule/index.pt 2004-11-13 21:05:19 UTC (rev 28450)
+++ Zope3/trunk/src/zope/app/apidoc/servicemodule/index.pt 2004-11-13 23:21:47 UTC (rev 28451)
@@ -40,12 +40,15 @@
</li>
<li tal:repeat="field fields">
- <b><code tal:content="field/name">field</code></b>
+ <b tal:attributes="class field/required_css">
+ <code tal:content="field/name">field</code>
+ <span tal:condition="field/required">*</span>
+ </b>
- <a href=""
tal:attributes="href string:../${field/iface/id}/apiindex.html">
<code tal:content="field/iface/name">IField</code></a>
- (<span tal:content="string:${field/required}, ">optional, </span>
- default = <code tal:content="field/default" />)<br>
+ (<span i18n:translate="">default</span> =
+ <code tal:content="field/default" />)<br />
<span tal:content="field/description">field desc</span>
</li>
@@ -94,5 +97,10 @@
</ul>
</div>
+ <p>
+ <em><b class="required">*</b> =
+ <span i18n:translate="">required</span></em>
+ </p>
+
</body>
</html>
Modified: Zope3/trunk/src/zope/app/apidoc/utilitymodule/index.pt
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/utilitymodule/index.pt 2004-11-13 21:05:19 UTC (rev 28450)
+++ Zope3/trunk/src/zope/app/apidoc/utilitymodule/index.pt 2004-11-13 23:21:47 UTC (rev 28451)
@@ -45,13 +45,16 @@
</li>
<li tal:repeat="field fields">
- <b><code tal:content="field/name">field</code></b>
+ <b tal:attributes="class field/required_css">
+ <code tal:content="field/name">field</code>
+ <span tal:condition="field/required">*</span>
+ </b>
- <a href=""
tal:attributes="
href string:../../../Interface/${field/iface/id}/apiindex.html">
<code tal:content="field/iface/name">IField</code></a>
- (<span tal:content="string:${field/required}, ">optional, </span>
- default = <code tal:content="field/default" />)<br>
+ (<span i18n:translate="">default</span> =
+ <code tal:content="field/default" />)<br />
<span tal:content="field/description">field desc</span>
</li>
@@ -87,6 +90,10 @@
</div>
+ <p>
+ <em><b class="required">*</b> =
+ <span i18n:translate="">required</span></em>
+ </p>
</body>
</html>
Modified: Zope3/trunk/src/zope/app/apidoc/zcmlmodule/browser.py
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/zcmlmodule/browser.py 2004-11-13 21:05:19 UTC (rev 28450)
+++ Zope3/trunk/src/zope/app/apidoc/zcmlmodule/browser.py 2004-11-13 23:21:47 UTC (rev 28451)
@@ -276,10 +276,12 @@
for ns, name, schema, handler, info in self.context.subdirs:
details = self._getInterfaceDetails(schema)
path = getPythonPath(handler)
- dirs.append({'namespace': ns,
- 'name': name,
- 'schema': details,
- 'handler': {'path': path,
- 'url': path.replace('.', '/')},
- 'info': info})
+ dirs.append({
+ 'namespace': ns,
+ 'name': name,
+ 'schema': details,
+ 'handler': {'path': path,
+ 'url': path.replace('.', '/')},
+ 'info': info,
+ })
return dirs
Modified: Zope3/trunk/src/zope/app/apidoc/zcmlmodule/index.pt
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/zcmlmodule/index.pt 2004-11-13 21:05:19 UTC (rev 28450)
+++ Zope3/trunk/src/zope/app/apidoc/zcmlmodule/index.pt 2004-11-13 23:21:47 UTC (rev 28451)
@@ -7,8 +7,15 @@
(<span tal:replace="structure view/getNamespaceName" />)
</h1>
- <div class="indent"
- tal:define="info view/getFileInfo"
+ <div class="details-subheader">
+ <div class="documentation" tal:content="structure schema/getDoc">
+ Here is the doc string
+ </div>
+ </div>
+
+ <br />
+
+ <div tal:define="info view/getFileInfo"
tal:condition="info">
<i i18n:translate="">File:</i>
<tal:var replace="info/file" />
@@ -20,14 +27,12 @@
</tal:block>
</div>
- <div class="indent"
- tal:condition="view/getInfo">
+ <div tal:condition="view/getInfo">
<i i18n:translate="">Info:</i>
<tal:block replace="view/getInfo" />
</div>
- <div class="indent"
- tal:define="handler view/getHandler"
+ <div tal:define="handler view/getHandler"
tal:condition="handler">
<i i18n:translate="">Handler:</i>
<a href=""
@@ -46,12 +51,6 @@
</a>
</div>
- <div class="indent">
- <div class="documentation" tal:content="structure schema/getDoc">
- Here is the doc string
- </div>
- </div>
-
<div class="indent"
tal:define="fields schema/getFields">
@@ -59,14 +58,16 @@
tal:condition="fields">
<li tal:repeat="field fields">
- <b><code tal:content="field/name">field</code></b>
+ <b tal:attributes="class field/required_css">
+ <code tal:content="field/name">field</code>
+ <span tal:condition="field/required">*</span>
+ </b>
- <a href=""
tal:attributes="href
string:../../../Class/${field/class/path}/index.html">
<code tal:content="field/class/name">Field</code></a>
- (<span tal:content="string:${field/required}, ">optional, </span>
- <span i18n:translate="">default</span> =
- <code tal:content="field/default" />)<br>
+ (<span i18n:translate="">default</span> =
+ <code tal:content="field/default" />)<br />
<span tal:content="structure field/description">field desc</span>
</li>
@@ -91,6 +92,14 @@
directive
</h3>
+ <div>
+ <div class="documentation" tal:content="structure dir/schema/getDoc">
+ Here is the doc string
+ </div>
+ </div>
+
+ <br />
+
<div class="indent"
tal:condition="dir/handler">
<i i18n:translate="">Handler:</i>
@@ -109,12 +118,6 @@
</a>
</div>
- <div class="indent">
- <div class="documentation" tal:content="structure dir/schema/getDoc">
- Here is the doc string
- </div>
- </div>
-
<div class="indent"
tal:define="fields dir/schema/getFields">
@@ -122,13 +125,16 @@
tal:condition="fields">
<li tal:repeat="field fields">
- <b><code tal:content="field/name">field</code></b>
+ <b tal:attributes="class field/required_css">
+ <code tal:content="field/name">field</code>
+ <span tal:condition="field/required">*</span>
+ </b>
- <a href=""
tal:attributes="href
string:../../../Interface/${field/iface/id}/apiindex.html">
<code tal:content="field/iface/name">IField</code></a>
- (<span tal:content="string:${field/required}, ">optional, </span>
- default = <code tal:content="field/default" />)<br>
+ (<span i18n:translate="">default</span> =
+ <code tal:content="field/default" />)<br />
<span tal:content="structure field/description">field desc</span>
</li>
@@ -144,5 +150,10 @@
</tal:omit-tag>
+ <p>
+ <em><b class="required">*</b> =
+ <span i18n:translate="">required</span></em>
+ </p>
+
</body>
</html>
More information about the Zope3-Checkins
mailing list