Merge pull request #9 from zopefoundation/issue4

Make restructuredtext the default doc format.

CHANGES.rst

@@ -20,6 +20,10 @@
 - Handle keyword only arguments and annotations in function signatures
   on Python 3.
 
+- Change the default documentation format to ``restructuredtext`` for
+  modules that do not specify a ``__docformat__``. Previously it was
+  ``structuredtext`` (STX).
+
 3.7.5 (2010-09-12)
 ==================
 

setup.py

@@ -31,7 +31,7 @@ def read(*rnames):
     'zope.app.folder >= 4.0.0',
     'zope.app.http >= 4.0.1',
     'zope.app.principalannotation >= 4.0.0',
-    'zope.app.rotterdam >= 4.0.0',
+    'zope.app.rotterdam >= 4.0.1',
     'zope.app.wsgi >= 4.1.0',
     'zope.applicationcontrol >= 4.0.0',
 
@@ -87,7 +87,6 @@ def read(*rnames):
         'Intended Audience :: Developers',
         'License :: OSI Approved :: Zope Public License',
         'Programming Language :: Python',
-        'Programming Language :: Python',
         'Programming Language :: Python :: 2',
         'Programming Language :: Python :: 2.7',
         'Programming Language :: Python :: 3',
@@ -117,7 +116,7 @@ def read(*rnames):
         'zope.app.onlinehelp >= 4.0.1',
         'zope.app.preference >= 4.0.0',
         'zope.app.publisher >= 4.0.0',
-        'zope.app.renderer >= 4.0.0',
+        'zope.app.renderer >= 4.1.0',
         'zope.app.tree >= 4.0.0',
         'zope.cachedescriptors',
         'zope.component>=3.8.0',

src/zope/app/apidoc/codemodule/browser/introspector.rst

@@ -106,7 +106,7 @@ example:
       <li>
         <b><code>get(key, default=None)</code>
         </b><br />
-        <div class="inline documentation"><p>See interface `IReadContainer`</p>
+        <div class="inline documentation"><p>See interface <cite>IReadContainer</cite></p>
         </div>
         <span class="small">
           <i>Interface:</i>

src/zope/app/apidoc/tests.py

@@ -149,8 +149,6 @@ def setUp(test):
     zope.component.testing.setUp()
     xmlconfig.file('configure.zcml', zope.app.renderer)
     zope.testing.module.setUp(test, 'zope.app.apidoc.doctest')
-    # Make RST the default for the sake of examples
-    test.globs['__docformat__'] = 'restructuredtext'
 
 def tearDown(test):
     zope.component.testing.tearDown()

src/zope/app/apidoc/utilities.py

@@ -356,10 +356,10 @@ def columnize(entries, columns=3):
 def getDocFormat(module):
     """Convert a module's __docformat__ specification to a renderer source
     id"""
-    format = getattr(module, '__docformat__', 'structuredtext').lower()
+    format = getattr(module, '__docformat__', 'restructuredtext').lower()
     # The format can also contain the language, so just get the first part
     format = format.split(' ')[0]
-    return _format_dict.get(format, 'zope.source.stx')
+    return _format_dict.get(format, 'zope.source.rest')
 
 
 def dedentString(text):

src/zope/app/apidoc/utilities.rst

@@ -645,25 +645,27 @@ to look up the factory id:
   >>> utilities.getDocFormat(apidoc)
   'zope.source.rest'
 
-By default structured text is returned:
+By default restructured text is returned:
 
-  >>> from zope.app.apidoc import tests
-  >>> utilities.getDocFormat(tests)
-  'zope.source.stx'
+  >>> utilities.getDocFormat(object())
+  'zope.source.rest'
 
-This is a sensible default, since we only decided later in development to
-endorse restructured text, so that many files are still in the structured text
-format. All converted and new modules will have the ``__docformat__`` attribute.
+This is a sensible default since much documentation is now written
+with Sphinx in mind (which of course defaults to rendering
+restructured text). As long as docutils' error reporting level is set
+sufficiently high (``severe``), unknown Sphinx directives and slightly
+malformed markup do not produce error messages, either on the console
+or in the generated HTML.
 
 The ``__docformat__`` attribute can also optionally specify a language field. We
 simply ignore it:
 
   >>> class Module(object):
   ...     pass
   >>> module = Module()
-  >>> module.__docformat__ = 'restructuredtext en'
+  >>> module.__docformat__ = 'structuredtext en'
   >>> utilities.getDocFormat(module)
-  'zope.source.rest'
+  'zope.source.stx'
 
 
 ``dedentString(text)``