[Zope3-checkins] SVN: Zope3/trunk/src/zope/app/apidoc/ The API doc
tool is now __docformat__ aware. It recognizes 'plaintext',
Stephan Richter
srichter at cosmos.phy.tufts.edu
Wed Jul 14 03:45:38 EDT 2004
Log message for revision 26524:
The API doc tool is now __docformat__ aware. It recognizes 'plaintext',
'structuredtext' (default) and 'restructuredtext'.
Especially Phil should be happy to see this, since his work finally pays
off. ;-)
Changed:
U Zope3/trunk/src/zope/app/apidoc/__init__.py
U Zope3/trunk/src/zope/app/apidoc/browser/apidoc.css
U Zope3/trunk/src/zope/app/apidoc/browser/apidoc.py
U Zope3/trunk/src/zope/app/apidoc/classmodule/browser.py
U Zope3/trunk/src/zope/app/apidoc/classmodule/tests.py
U Zope3/trunk/src/zope/app/apidoc/ifacemodule/browser.py
U Zope3/trunk/src/zope/app/apidoc/ifacemodule/tests.py
U Zope3/trunk/src/zope/app/apidoc/utilities.py
-=-
Modified: Zope3/trunk/src/zope/app/apidoc/__init__.py
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/__init__.py 2004-07-14 06:01:10 UTC (rev 26523)
+++ Zope3/trunk/src/zope/app/apidoc/__init__.py 2004-07-14 07:45:38 UTC (rev 26524)
@@ -33,7 +33,7 @@
items of the container are all registered utilities for
`IDocumentationModule`.
- Demonstration::
+ Demonstration:
>>> doc = APIDocumentation(None, '++apidoc++')
>>> doc.get('ZCML').title
Modified: Zope3/trunk/src/zope/app/apidoc/browser/apidoc.css
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/browser/apidoc.css 2004-07-14 06:01:10 UTC (rev 26523)
+++ Zope3/trunk/src/zope/app/apidoc/browser/apidoc.css 2004-07-14 07:45:38 UTC (rev 26524)
@@ -119,6 +119,22 @@
margin: 0.5em 2em;
}
+
+div.inline-documentation h1 {
+ font-size: 120%;
+ padding: 0;
+ margin: 0;
+ margin-bottom: 0.5em;
+}
+
+div.inline-documentation h2 {
+ font-size: 110%;
+ font-style: italic;
+ padding: 0;
+ margin: 0;
+ margin-bottom: 0.5em;
+}
+
div.inline-documentation h3 {
font-style: italic;
font-weight: normal;
Modified: Zope3/trunk/src/zope/app/apidoc/browser/apidoc.py
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/browser/apidoc.py 2004-07-14 06:01:10 UTC (rev 26523)
+++ Zope3/trunk/src/zope/app/apidoc/browser/apidoc.py 2004-07-14 07:45:38 UTC (rev 26524)
@@ -15,7 +15,7 @@
$Id$
"""
-from zope.app.apidoc.utilities import stx2html
+from zope.app.apidoc.utilities import renderText
class APIDocumentationView(object):
"""View for the API Documentation"""
@@ -38,6 +38,6 @@
items.sort()
return [{'name': name,
'title': module.title,
- # FIXME: Seems like stx2html() doesn't like message ids
- 'description': stx2html(module.description)}
+ 'description': renderText(module.description,
+ module.__class__.__module__)}
for name, module in items ]
Modified: Zope3/trunk/src/zope/app/apidoc/classmodule/browser.py
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/classmodule/browser.py 2004-07-14 06:01:10 UTC (rev 26523)
+++ Zope3/trunk/src/zope/app/apidoc/classmodule/browser.py 2004-07-14 07:45:38 UTC (rev 26524)
@@ -25,7 +25,7 @@
from zope.app import zapi
from zope.app.i18n import ZopeMessageIDFactory as _
-from zope.app.apidoc.utilities import getPythonPath, stx2html, columnize
+from zope.app.apidoc.utilities import getPythonPath, renderText, columnize
from zope.app.apidoc.utilities import getPermissionIds, getFunctionSignature
from zope.app.apidoc.utilities import getPublicAttributes
from zope.app.apidoc.utilities import getInterfaceForAttribute
@@ -113,7 +113,7 @@
"""Represents the details of the function."""
def getDocString(self):
- r"""Get the doc string of the class STX formatted.
+ r"""Get the doc string of the class in a rendered format.
Example::
@@ -123,7 +123,8 @@
>>> view.getDocString()
'<p>This is the foo function.</p>\n'
"""
- return stx2html(self.context.getDocString() or '', 3)
+ return renderText(self.context.getDocString() or '',
+ zapi.getParent(self.context).getPath())
def getAttributes(self):
@@ -275,14 +276,14 @@
>>> methods = view.getMethods()
>>> pprint(methods[-2:])
- [[('doc', ''),
+ [[('doc', u''),
('interface',
'zope.interface.common.mapping.IEnumerableMapping'),
('name', 'keys'),
('read_perm', None),
('signature', '()'),
('write_perm', None)],
- [('doc', ''),
+ [('doc', u''),
('interface',
'zope.interface.common.mapping.IEnumerableMapping'),
('name', 'values'),
@@ -295,7 +296,8 @@
for name, attr, iface in klass.getMethods():
entry = {'name': name,
'signature': getFunctionSignature(attr),
- 'doc': stx2html(attr.__doc__ or '', 3),
+ 'doc': renderText(attr.__doc__ or '',
+ zapi.getParent(self.context).getPath()),
'interface': getPythonPath(iface)}
entry.update(getPermissionIds(name, klass.getSecurityChecker()))
methods.append(entry)
@@ -314,9 +316,10 @@
>>> view = getClassDetailsView()
>>> print view.getDoc()[:59]
- <h3>Represent the Documentation of any possible class.</h3>
+ <h1>Represent the Documentation of any possible class.</h1>
"""
- return stx2html(self.context.getDocString() or '', 3)
+ return renderText(self.context.getDocString() or '',
+ zapi.getParent(self.context).getPath())
class ModuleDetails(object):
@@ -343,7 +346,7 @@
lines = text.strip().split('\n')
# Get rid of possible CVS id.
lines = [line for line in lines if not line.startswith('$Id')]
- return stx2html('\n'.join(lines), 3)
+ return renderText('\n'.join(lines), self.context.getPath())
def getEntries(self, columns=True):
"""Return info objects for all modules and classes in this module.
Modified: Zope3/trunk/src/zope/app/apidoc/classmodule/tests.py
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/classmodule/tests.py 2004-07-14 06:01:10 UTC (rev 26523)
+++ Zope3/trunk/src/zope/app/apidoc/classmodule/tests.py 2004-07-14 07:45:38 UTC (rev 26524)
@@ -16,18 +16,25 @@
$Id$
"""
import unittest
+from zope.component.interfaces import IFactory
from zope.interface import Interface, directlyProvides
from zope.publisher.browser import TestRequest
from zope.testing.doctestunit import DocTestSuite
+
from zope.app import zapi
+from zope.app.location.traversing import LocationPhysicallyLocatable
+from zope.app.renderer.rest import ReStructuredTextSourceFactory
+from zope.app.renderer.rest import IReStructuredTextSource
+from zope.app.renderer.rest import ReStructuredTextToHTMLRenderer
+from zope.app.renderer.stx import StructuredTextSourceFactory
+from zope.app.renderer.stx import IStructuredTextSource
+from zope.app.renderer.stx import StructuredTextToHTMLRenderer
from zope.app.tests import placelesssetup, ztapi
-
from zope.app.traversing.browser import AbsoluteURL, SiteAbsoluteURL
from zope.app.traversing.interfaces import ITraversable, ITraverser
from zope.app.traversing.interfaces import IPhysicallyLocatable
from zope.app.traversing.interfaces import IContainmentRoot
from zope.app.traversing.adapters import DefaultTraversable
-from zope.app.location.traversing import LocationPhysicallyLocatable
from zope.app.traversing.adapters import RootPhysicallyLocatable
from zope.app.traversing.adapters import Traverser
@@ -56,7 +63,17 @@
ztapi.browserView(Interface, "absolute_url", AbsoluteURL)
ztapi.browserView(IContainmentRoot, "absolute_url", SiteAbsoluteURL)
+ # Register Renderer Components
+ ztapi.provideUtility(IFactory, StructuredTextSourceFactory,
+ 'zope.source.stx')
+ ztapi.provideUtility(IFactory, ReStructuredTextSourceFactory,
+ 'zope.source.rest')
+ ztapi.browserView(IStructuredTextSource, '',
+ StructuredTextToHTMLRenderer)
+ ztapi.browserView(IReStructuredTextSource, '',
+ ReStructuredTextToHTMLRenderer)
+
def tearDown():
placelesssetup.tearDown()
Modified: Zope3/trunk/src/zope/app/apidoc/ifacemodule/browser.py
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/ifacemodule/browser.py 2004-07-14 06:01:10 UTC (rev 26523)
+++ Zope3/trunk/src/zope/app/apidoc/ifacemodule/browser.py 2004-07-14 07:45:38 UTC (rev 26524)
@@ -24,7 +24,7 @@
from zope.app import zapi
from zope.app.i18n import ZopeMessageIDFactory as _
-from zope.app.apidoc.utilities import getPythonPath, stx2html
+from zope.app.apidoc.utilities import getPythonPath, renderText
from zope.app.apidoc.classmodule import classRegistry
def _get(iface, type):
@@ -197,7 +197,7 @@
>>> details.getDoc()[:34]
'<h1>This is the Foo interface</h1>'
"""
- return stx2html(self.context.__doc__)
+ return renderText(self.context.__doc__, self.context.__module__)
def getBases(self):
"""Get all bases of this class
@@ -267,7 +267,7 @@
if not IMethod.providedBy(attr) and not IField.providedBy(attr):
attrs.append(attr)
return [{'name': attr.getName(),
- 'doc': stx2html(attr.getDoc() or '', 3)}
+ 'doc': renderText(attr.getDoc() or '', iface.__module__)}
for attr in attrs]
def getMethods(self):
@@ -290,7 +290,8 @@
"""
return [{'name': method.getName(),
'signature': method.getSignatureString(),
- 'doc': stx2html(method.getDoc() or '', 3)}
+ 'doc': renderText(method.getDoc() or '',
+ self.context.__module__)}
for method in _get(self.context, IMethod).values()]
def getFields(self):
Modified: Zope3/trunk/src/zope/app/apidoc/ifacemodule/tests.py
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/ifacemodule/tests.py 2004-07-14 06:01:10 UTC (rev 26523)
+++ Zope3/trunk/src/zope/app/apidoc/ifacemodule/tests.py 2004-07-14 07:45:38 UTC (rev 26524)
@@ -16,6 +16,7 @@
$Id$
"""
import unittest
+
from zope.component.interfaces import IFactory
from zope.component.factory import Factory
from zope.interface import implements, Interface, Attribute
@@ -23,19 +24,23 @@
from zope.publisher.browser import TestRequest
from zope.schema import TextLine, Text
from zope.testing.doctestunit import DocTestSuite
+
from zope.app import zapi
from zope.app.component.interface import provideInterface
from zope.app.location import LocationProxy
+from zope.app.location.traversing import LocationPhysicallyLocatable
+from zope.app.renderer.rest import ReStructuredTextSourceFactory
+from zope.app.renderer.rest import IReStructuredTextSource
+from zope.app.renderer.rest import ReStructuredTextToHTMLRenderer
+from zope.app.renderer.stx import StructuredTextSourceFactory
+from zope.app.renderer.stx import IStructuredTextSource
+from zope.app.renderer.stx import StructuredTextToHTMLRenderer
from zope.app.tests import placelesssetup, ztapi
from zope.app.traversing.interfaces import IContainmentRoot
-
+from zope.app.traversing.interfaces import IPhysicallyLocatable
from zope.app.tree.interfaces import IUniqueId
from zope.app.tree.adapters import LocationUniqueId
-from zope.app.traversing.interfaces import IPhysicallyLocatable
-from zope.app.location import LocationProxy
-from zope.app.location.traversing import LocationPhysicallyLocatable
-
from zope.app.apidoc.classmodule import classRegistry
from zope.app.apidoc.ifacemodule import IInterfaceModule, InterfaceModule
from zope.app.apidoc.ifacemodule.menu import IModule
@@ -95,6 +100,16 @@
ztapi.provideAdapter(None, IPhysicallyLocatable,
LocationPhysicallyLocatable)
+ # Register Renderer Components
+ ztapi.provideUtility(IFactory, StructuredTextSourceFactory,
+ 'zope.source.stx')
+ ztapi.provideUtility(IFactory, ReStructuredTextSourceFactory,
+ 'zope.source.rest')
+ ztapi.browserView(IStructuredTextSource, '',
+ StructuredTextToHTMLRenderer)
+ ztapi.browserView(IReStructuredTextSource, '',
+ ReStructuredTextToHTMLRenderer)
+
# Make IFoo adapter interesting.
ztapi.provideAdapter(IBar, IFoo, object)
Modified: Zope3/trunk/src/zope/app/apidoc/utilities.py
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/utilities.py 2004-07-14 06:01:10 UTC (rev 26523)
+++ Zope3/trunk/src/zope/app/apidoc/utilities.py 2004-07-14 07:45:38 UTC (rev 26524)
@@ -18,6 +18,7 @@
__docformat__ = 'restructuredtext'
import re
+import sys
import types
import inspect
from os.path import dirname
@@ -25,10 +26,12 @@
import zope
from zope.interface import implements, implementedBy
from zope.proxy import removeAllProxies
+from zope.publisher.browser import TestRequest
from zope.security.checker import getCheckerForInstancesOf, Global
from zope.security.interfaces import INameBasedChecker
+
+from zope.app import zapi
from zope.app.i18n import ZopeMessageIDFactory as _
-
from zope.app.container.interfaces import IReadContainer
__metaclass__ = type
@@ -148,30 +151,6 @@
return '%s.%s' %(module, obj.__name__)
-def stx2html(text, level=1):
- r"""Convert STX text to HTML.
-
- Example::
-
- >>> text = 'Header\n\n Normal text goes here.'
-
- >>> stx2html(text)
- '<h1>Header</h1>\n<p> Normal text goes here.</p>\n'
-
- >>> stx2html(text, level=3)
- '<h3>Header</h3>\n<p> Normal text goes here.</p>\n'
-
- >>> stx2html(text, level=6)
- '<h6>Header</h6>\n<p> Normal text goes here.</p>\n'
- """
- from zope.structuredtext.document import Document
- from zope.structuredtext.html import HTML
- doc = Document()(text)
- html = HTML()(doc, level)
- html = _remove_html_overhead.sub(r'\1', html)
- return html
-
-
def _evalId(id):
id = removeAllProxies(id)
if isinstance(id, Global):
@@ -519,3 +498,35 @@
if col:
columns.append(col)
return columns
+
+_format_dict = {
+ 'plaintext': 'zope.source.plaintext',
+ 'structuredtext': 'zope.source.stx',
+ 'restructuredtext': 'zope.source.rest'
+ }
+
+
+def getDocFormat(module):
+ """Convert a module's __docformat__ specification to a renderer source
+ id"""
+ format = getattr(module, '__docformat__', 'structuredtext').lower()
+ return _format_dict.get(format, 'zope.source.stx')
+
+
+def renderText(text, module=None, format=None):
+ if module is not None:
+ if isinstance(module, (str, unicode)):
+ module = sys.modules.get(module, None)
+ format = getDocFormat(module)
+
+ if format is None:
+ format = 'zope.source.stx'
+
+ assert format in _format_dict.values()
+
+ if text:
+ source = zapi.createObject(None, format, text)
+ renderer = zapi.getView(source, '', TestRequest())
+ return renderer.render()
+ else:
+ return u''
More information about the Zope3-Checkins
mailing list