Mercurial > genshi > mirror

changeset 426:a1955bc39924 trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add epydoc-based API doc generation to the build.
author cmlenz
date Thu, 22 Mar 2007 13:10:55 +0000
parents 073640758a42
children 55c574767df2
files doc/epydoc.conf doc/style/apidoc.css setup.py
diffstat 3 files changed, 173 insertions(+), 2 deletions(-) [+]
line wrap: on
line diff
new file mode 100644
--- /dev/null
+++ b/doc/epydoc.conf
@@ -0,0 +1,24 @@
+[epydoc]
+
+name: Genshi
+url: http://genshi.edgewall.org/
+modules: genshi
+verbosity: 1
+
+# Extraction
+docformat: restructuredtext
+parse: yes
+introspect: yes
+exclude: .*\.tests.*
+inheritance: listed
+private: no
+imports: no
+include-log: no
+
+# HTML output
+output: html
+target: doc/api/
+css: doc/style/apidoc.css
+top: genshi
+frames: no
+sourcecode: no
new file mode 100644
--- /dev/null
+++ b/doc/style/apidoc.css
@@ -0,0 +1,129 @@
+html { background: #4b4d4d url(../style/bkgnd_pattern.png); margin: 0;
+  padding: 1em 1em 3em;
+}
+body { background: #fff url(../style/vertbars.png) repeat-x;
+  border: 1px solid #000; color: #000; margin: 1em 0; padding: 0 1em 1em;
+}
+body, th, td {
+  font: normal small Verdana,Arial,'Bitstream Vera Sans',Helvetica,sans-serif;
+}
+h1, h2, h3, h4 {
+  font-family: Arial,Verdana,'Bitstream Vera Sans',Helvetica,sans-serif;
+  font-weight: bold; letter-spacing: -0.018em;
+}
+h1 { font-size: 19px; margin: 2em 0 .5em; }
+h2 { font-size: 16px; margin: 1.5em 0 .5em; }
+h3 { font-size: 14px; margin: 1.2em 0 .5em; }
+hr { border: none;  border-top: 1px solid #ccb; margin: 2em 0; }
+p { margin: 0 0 1em; }
+:link, :visited { text-decoration: none; border-bottom: 1px dotted #bbb;
+  color: #b00;
+}
+:link:hover, :visited:hover { background-color: #eee; color: #555; }
+
+table { border: none; border-collapse: collapse; }
+
+table.navbar { background: #000; color: #fff; margin: 2em 0 .33em; }
+table.navbar th { border: 1px solid #000; font-weight: bold; padding: 1px; }
+table.navbar :link, table.navbar :visited { border: none; color: #fff; }
+table.navbar :link:hover, table.navbar :visited:hover { background: none;
+  text-decoration: underline overline;
+}
+table.navbar th.navbar-select { background: #fff; color: #000; }
+span.breadcrumbs { color: #666; font-size: 95%; }
+h1.epydoc { border: none; color: #666;
+  font-size: x-large; margin: 1em 0 0; padding: 0;
+}
+pre.base-tree { color: #666; margin: 0; padding: 0; }
+pre.base-tree :link, pre.base-tree :visited { border: none; }
+pre.py-doctest, pre.variable, pre.rst-literal-block { background: #eee;
+  border: 1px solid #e6e6e6; color: #000; margin: 1em; padding: .25em;
+  overflow: auto;
+}
+pre.variable { margin: 0; }
+
+/* Summary tables */
+
+table.summary { margin: .5em 0; }
+table.summary tr.table-header { background: #f7f7f0; }
+table.summary td.table-header { color: #666; font-weight: bold; }
+table.summary th, table.summary td { border: 1px solid #d7d7d7; }
+table.summary th th, table.summary td td { border: none; }
+table.summary td.summary table td { color: #666; font-size: 90%; }
+table.summary td.summary table br { display: none; }
+p.indent-wrapped-lines { color: #999; font-size: 85%; margin: 0;
+  padding: 0 0 0 7em; text-indent: -7em;
+}
+p.indent-wrapped-lines code { color: #999; font-size: 115%; }
+p.indent-wrapped-lines :link, p.indent-wrapped-lines :visited { border: none; }
+.summary-sig { display: block; font-family: monospace; font-size: 120%;
+  margin-bottom: .5em;
+}
+.summary-sig-name { font-weight: bold; }
+.summary-sig-arg { color: #333; }
+.summary-sig :link, .summary-sig :visited { border: none; }
+.summary-name { font-family: monospace; font-weight: bold; }
+
+/* Details tables */
+
+table.details { margin: 2em 0 0; }
+div table.details { margin-top: 0; }
+table.details tr.table-header { background: transparent; }
+table.details td.table-header { border-bottom: 1px solid #ccc; padding: 2em 0 0; }
+table.details span.table-header {
+  font: bold 140% Arial,Verdana,'Bitstream Vera Sans',Helvetica,sans-serif;
+  letter-spacing: -0.018em;
+}
+table.details th, table.details td { border: none; }
+table.details th th, table.details td td { border: none; }
+table.details td { padding-left: 2em; }
+table.details td td { padding-left: 0; }
+table.details h3.epydoc { margin-left: -2em; }
+table.details h3.epydoc .sig { color: #999; font-family: monospace; }
+table.details h3.epydoc .sig-name { color: #000; }
+table.details h3.epydoc .sig-arg { color: #666; }
+table.details h3.epydoc .sig-default { font-size: 95%; font-weight: normal; }
+table.details h3.epydoc .sig-default code { font-weight: normal; }
+table.details h3.epydoc .fname { color: #999; font-size: 90%;
+  font-style: italic; font-weight: normal; line-height: 1.6em;
+}
+
+dl dt { color: #666; margin-top: 1em; }
+dl dd { margin: 0; padding-left: 2em; }
+dl.fields { margin: 1em 0; padding: 0; }
+dl.fields dt { color: #666; margin-top: 1em; }
+dl.fields dd ul { margin: 0; padding: 0; }
+div.fields { font-size: 90%; margin: 0 0 2em 2em; }
+div.fields p { margin-bottom: 0.5em; }
+
+table td.footer { color: #999; font-size: 85%; margin-top: 3em;
+  padding: 0 3em 1em; position: absolute; width: 80%; }
+table td.footer :link, table td.footer :visited { border: none; color: #999; }
+table td.footer :link:hover, table td.footer :visited:hover {
+  background: transparent; text-decoration: underline;
+}
+
+/* Syntax highlighting */
+
+.py-prompt, .py-more, .variable-ellipsis, .variable-op { color: #999; }
+.variable-group { color: #666; font-weight: bold; }
+.py-string, .variable-string, .variable-quote { color: #093; }
+.py-comment { color: #06f; font-style: italic; }
+.py-keyword { color: #00f; }
+.py-output { background: #f6f6f0; font-weight: bold; }
+
+/* Index */
+
+table.link-index { background: #f6f6f0; border: none; margin-top: 1em; }
+table.link-index td.link-index { border: none; font-family: monospace;
+  font-weight: bold; padding: .5em 1em;
+}
+table.link-index td table, table.link-index td td { border: none; }
+table.link-index .index-where { color: #999;
+  font-family: Verdana,Arial,'Bitstream Vera Sans',Helvetica,sans-serif;
+  font-size: 90%; font-weight: normal; line-height: 1.6em;
+}
+table.link-index .index-where :link, table.link-index .index-where :visited {
+  border: none; color: #666;
+}
+h2.epydoc { color: #999; font-size: 200%; line-height: 10px; }
--- a/setup.py
+++ b/setup.py
@@ -20,6 +20,7 @@
     from setuptools import setup
 except ImportError:
     from distutils.core import setup
+import sys
 
 
 class build_doc(Command):
@@ -34,7 +35,8 @@
 
     def run(self):
         from docutils.core import publish_cmdline
-        conf = os.path.join('doc', 'docutils.conf')
+        docutils_conf = os.path.join('doc', 'docutils.conf')
+        epydoc_conf = os.path.join('doc', 'epydoc.conf')
 
         for source in glob('doc/*.txt'):
             dest = os.path.splitext(source)[0] + '.html'
@@ -42,7 +44,23 @@
                    os.path.getmtime(dest) < os.path.getmtime(source):
                 print 'building documentation file %s' % dest
                 publish_cmdline(writer_name='html',
-                                argv=['--config=%s' % conf, source, dest])
+                                argv=['--config=%s' % docutils_conf, source,
+                                      dest])
+
+        try:
+            from epydoc import cli
+            old_argv = sys.argv[1:]
+            sys.argv[1:] = [
+                '--config=%s' % epydoc_conf,
+                '--no-private', # epydoc bug, not read from config
+                '--simple-term',
+                '--verbose'
+            ]
+            cli.cli()
+            sys.argv[1:] = old_argv
+
+        except ImportError:
+            print 'epydoc not installed, skipping API documentation.'
 
 
 class test_doc(Command):
Copyright (C) 2012-2017 Edgewall Software