Skip to content
Browse files

#8695: add support for alternate API reference using [http://epydoc.s…

…ourceforge.net/ Epydoc].

While Sphinx is nice for getting exact control over the generated API
documentation, Epydoc can be used to get a full coverage of the whole
API automatically.

To get started:
{{{
$ make apiref
}}}

This will generate the Epydoc documentation in `build/doc/epydoc`.

The epydoc.css stylesheet and related .png were copied from
http://svn.edgewall.org/repos/edgewall/tools/doc/style/ (revision 35).


git-svn-id: http://svn.edgewall.org/repos/trac/trunk@10280 af82e41b-90c4-0310-8c96-b1721e28e2e2
  • Loading branch information...
1 parent ad228f0 commit acffec39b47c2512d1316d5500d980d73e476139 cboos committed Oct 24, 2010
Showing with 360 additions and 4 deletions.
  1. +23 −4 Makefile
  2. +5 −0 Makefile.cfg.sample
  3. +153 −0 doc/epydoc.conf
  4. +136 −0 doc/epydoc.css
  5. BIN doc/images/bkgnd_pattern.png
  6. BIN doc/images/vertbars.png
  7. +43 −0 doc/runepydoc.py
View
27 Makefile
@@ -73,12 +73,16 @@ define HELP
---------------- Documentation tasks
- apidoc generate the API documentation using Sphinx into
+ apidoc|sphinx generate the API documentation using Sphinx into
build/doc/<sphinxformat>
+ apiref|epydoc generate the full API reference using Epydoc
+
[sphinxformat=...] format of the generated documentation (defaults to html)
- [sphinxopts=...] variable containing extra options for sphinx
+ [sphinxopts=...] variable containing extra options for Sphinx
[sphinxopts-html=...] variable containing extra options used for html format
+ [epydocopts=...] variable containing extra options for Epydoc
+ [dotpath=/.../dot] path to Graphviz' dot program
endef
export HELP
@@ -400,7 +404,7 @@ endif
#
# ----------------------------------------------------------------------------
-.PHONY: apidoc clean-doc
+.PHONY: apidoc sphinx apiref epydoc clean-doc
sphinxformat ?= html
@@ -411,14 +415,29 @@ BUILDDIR ?= build/doc/$(sphinxformat)
PAPER ?= a4
sphinxopts-latex ?= -D latex_paper_size=$(PAPER)
+sphinx: apidoc
apidoc:
@$(SPHINXBUILD) -b $(sphinxformat) \
$(sphinxopts) $(sphinxopts-$(sphinxformat)) \
-d build/doc/doctree \
doc $(BUILDDIR)
+
+epydoc: apiref
+apiref: doc-images
+ @python doc/runepydoc.py --config=doc/epydoc.conf \
+ $(epydocopts) $(if $(dotpath),--dotpath=$(dotpath))
+
+doc-images: $(addprefix build/,$(wildcard doc/images/*.png))
+build/doc/images/%: doc/images/% | build/doc/images
+ @cp $(<) $(@)
+build/doc/images:
+ @mkdir -p $(@)
+
clean-doc:
- @rm -fr build/doc
+ rm -fr build/doc
+
+
# ============================================================================
#
View
5 Makefile.cfg.sample
@@ -37,6 +37,11 @@ env = ~/tracenvs
auth = *,~/tracenvs/htdigest.realm,realm
# ----------------------------------------------------------------------------
+# Settings for the documentation
+
+dotpath = /usr/local/bin/dot
+
+# ----------------------------------------------------------------------------
# Custom rules
.PHONY: bigtest
View
153 doc/epydoc.conf
@@ -0,0 +1,153 @@
+# from http://epydoc.sourceforge.net/manual-reference.html#command-line-usage
+
+[epydoc] # Epydoc section marker (required by ConfigParser)
+
+# The list of objects to document. Objects can be named using
+# dotted names, module filenames, or package directory names.
+# Alases for this option include "objects" and "values".
+modules: trac/, tracopt/
+
+
+# The type of output that should be generated. Should be one
+# of: html, text, latex, dvi, ps, pdf.
+output: html
+
+# The path to the output directory. May be relative or absolute.
+target: build/doc/epydoc
+
+# An integer indicating how verbose epydoc should be. The default
+# value is 0; negative values will supress warnings and errors;
+# positive values will give more verbose output.
+verbosity: 1
+
+# A boolean value indicating that Epydoc should show a tracaback
+# in case of unexpected error. By default don't show tracebacks
+debug: 0
+
+# If True, don't try to use colors or cursor control when doing
+# textual output. The default False assumes a rich text prompt
+simple-term: 0
+
+
+### Generation options
+
+# The default markup language for docstrings, for modules that do
+# not define __docformat__. Defaults to epytext.
+docformat: reStructuredText
+
+# Whether or not parsing should be used to examine objects.
+parse: yes
+
+# Whether or not introspection should be used to examine objects.
+introspect: yes
+
+# Don't examine in any way the modules whose dotted name match this
+# regular expression pattern.
+#exclude
+
+# Don't perform introspection on the modules whose dotted name match this
+# regular expression pattern.
+#exclude-introspect
+
+# Don't perform parsing on the modules whose dotted name match this
+# regular expression pattern.
+#exclude-parse
+
+# The format for showing inheritance objects.
+# It should be one of: 'grouped', 'listed', 'included'.
+inheritance: listed
+
+# Whether or not to inclue private variables. (Even if included,
+# private variables will be hidden by default.)
+private: no
+
+# Whether or not to list each module's imports.
+imports: yes
+
+# Whether or not to include syntax highlighted source code in
+# the output (HTML only).
+sourcecode: yes
+
+# Whether or not to includea a page with Epydoc log, containing
+# effective option at the time of generation and the reported logs.
+include-log: yes
+
+
+### Output options
+
+# The documented project's name.
+name: Trac
+
+# The CSS stylesheet for HTML output. Can be the name of a builtin
+# stylesheet, or the name of a file.
+css: doc/epydoc.css
+
+# The documented project's URL.
+url: http://trac.edgewall.org
+
+# HTML code for the project link in the navigation bar. If left
+# unspecified, the project link will be generated based on the
+# project's name and URL.
+#link: <a href="somewhere">My Cool Project</a>
+
+# The "top" page for the documentation. Can be a URL, the name
+# of a module or class, or one of the special names "trees.html",
+# "indices.html", or "help.html"
+top: index.html
+
+# An alternative help file. The named file should contain the
+# body of an HTML file; navigation bars will be added to it.
+#help: my_helpfile.html
+
+# Whether or not to include a frames-based table of contents.
+frames: no
+
+# Whether each class should be listed in its own section when
+# generating LaTeX or PDF output.
+separate-classes: no
+
+
+### API linking options
+
+# Define a new API document. A new interpreted text role
+# will be created
+#external-api: epydoc
+
+# Use the records in this file to resolve objects in the API named NAME.
+#external-api-file: epydoc:api-objects.txt
+
+# Use this URL prefix to configure the string returned for external API.
+#external-api-root: epydoc:http://epydoc.sourceforge.net/api
+
+
+### Graph options
+
+# The list of graph types that should be automatically included
+# in the output. Graphs are generated using the Graphviz "dot"
+# executable. Graph types include: "classtree", "callgraph",
+# "umlclass". Use "all" to include all graph types
+#graph: umlclasstree
+## prefer the ASCII-art version for now, see comments in doc/runepydoc.py
+
+# The path to the Graphviz "dot" executable, used to generate
+# graphs.
+## dotpath: /usr/local/bin/dot
+## see Makefile
+
+# The name of one or more pstat files (generated by the profile
+# or hotshot module). These are used to generate call graphs.
+## pstat: profile.out
+
+# Specify the font used to generate Graphviz graphs.
+# (e.g., helvetica or times).
+graph-font: Helvetica
+
+# Specify the font size used to generate Graphviz graphs.
+graph-font-size: 10
+
+
+### Return value options
+
+# The condition upon which Epydoc should exit with a non-zero
+# exit status. Possible values are error, warning, docstring_warning
+#fail-on: error
View
136 doc/epydoc.css
@@ -0,0 +1,136 @@
+html { background: #4b4d4d url(images/bkgnd_pattern.png); margin: 0;
+ padding: 1em 1em 3em;
+}
+body { background: #fff url(images/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.group-header { background: #f7f7f0; color: #666;
+ font-size: 90%; font-weight: bold; text-align: left;
+}
+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; }
+table.summary td.summary span.summary-type { font-family: monospace;
+ font-size: 90%;
+}
+table.summary td.summary span.summary-type code { font-size: 110%; }
+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; color: #666; 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; }
View
BIN doc/images/bkgnd_pattern.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN doc/images/vertbars.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
43 doc/runepydoc.py
@@ -0,0 +1,43 @@
+# Simple wrapper script needed to run epydoc
+
+import sys
+
+try:
+ from epydoc.cli import cli
+except ImportError:
+ print>>sys.stderr, "No epydoc installed (see http://epydoc.sourceforge.net)"
+ sys.exit(2)
+
+
+# Epydoc 3.0.1 has some trouble running with recent Docutils (>= 0.6),
+# so we work around this bug, following the lines of the fix in
+# https://bugs.gentoo.org/attachment.cgi?id=210118
+# (see http://bugs.gentoo.org/287546)
+
+try:
+ from docutils.nodes import Text
+ if not hasattr(Text, 'data'):
+ setattr(Text, 'data', property(lambda self: self.astext()))
+except ImportError:
+ print>>sys.stderr, "docutils is needed for running epydoc " \
+ "(see http://docutils.sourceforge.net)"
+ sys.exit(2)
+
+# Epydoc doesn't allow much control over the generated graphs. This is
+# bad especially for the class graph for Component which has a lot of
+# subclasses, so we need to force Left-to-Right mode.
+
+# from epydoc.docwriter.html import HTMLWriter
+# HTMLWriter_render_graph = HTMLWriter.render_graph
+# def render_graph_LR(self, graph):
+# if graph:
+# graph.body += 'rankdir=LR\n'
+# return HTMLWriter_render_graph(self, graph)
+# HTMLWriter.render_graph = render_graph_LR
+
+# Well, LR mode doesn't really look better...
+# the ASCII-art version seems better in most cases.
+
+# run epydoc
+cli()
+

0 comments on commit acffec3

Please sign in to comment.
Something went wrong with that request. Please try again.