├── src ├── scripts │ ├── .cvsignore │ ├── epydocgui │ ├── epydoc │ ├── epydoc.pyw │ ├── epydoc.py │ └── apirst2html.py ├── .cvsignore ├── MANIFEST.in ├── epydoc │ ├── docwriter │ │ ├── __init__.py │ │ └── html_help.py │ ├── test │ │ ├── py2 │ │ │ ├── zope3.doctest │ │ │ ├── zope2.doctest │ │ │ ├── restructuredtext.doctest │ │ │ └── encoding.doctest │ │ ├── py3 │ │ │ ├── zope3.doctest │ │ │ ├── zope2.doctest │ │ │ ├── restructuredtext.doctest │ │ │ └── encoding.doctest │ │ ├── javadoc.doctest │ │ ├── plaintext.doctest │ │ ├── cli.doctest │ │ ├── __init__.py │ │ └── apidoc.doctest │ ├── seven.py │ ├── markup │ │ └── plaintext.py │ ├── log.py │ └── __init__.py ├── LICENSE.txt ├── tools │ ├── mkdispatch.py │ ├── rst2html.py │ └── sty2html.py ├── README.txt ├── setup.py └── Makefile ├── doc ├── .cvsignore ├── sflogo.png ├── epydoc_gui.png ├── pycon-epydoc.pdf ├── epydoc-slides.pdf ├── epydoc-slides.ppt ├── home.thumbnail.png ├── index.thumbnail.png ├── pysrc.thumbnail.png ├── uml.thumbnail.png ├── epydoc_guiconfig.png ├── epytext_example.py ├── rst-template.txt ├── rst-template2.txt ├── inh_example.py ├── manual.txt ├── future.html ├── license.html ├── doctest │ └── index.html ├── history.html ├── docstrings.html ├── pycon-epydoc.html ├── epytextintro.html ├── manual-docstring.txt ├── custom.css ├── epydoc.css ├── configfile.html ├── manual-install.txt ├── docutils.css ├── index.html ├── stylesheet.html ├── othermarkup.html └── installing.html ├── README.md └── .gitignore /src/scripts/.cvsignore: -------------------------------------------------------------------------------- 1 | *.pyc -------------------------------------------------------------------------------- /src/.cvsignore: -------------------------------------------------------------------------------- 1 | MANIFEST 2 | build 3 | dist 4 | -------------------------------------------------------------------------------- /doc/.cvsignore: -------------------------------------------------------------------------------- 1 | *-man.html 2 | api 3 | *.pyc 4 | examples 5 | 6 | -------------------------------------------------------------------------------- /doc/sflogo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nltk/epydoc/HEAD/doc/sflogo.png -------------------------------------------------------------------------------- /doc/epydoc_gui.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nltk/epydoc/HEAD/doc/epydoc_gui.png -------------------------------------------------------------------------------- /doc/pycon-epydoc.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nltk/epydoc/HEAD/doc/pycon-epydoc.pdf -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | epydoc 2 | ====== 3 | 4 | Automatic API Documentation Generation for Python 5 | -------------------------------------------------------------------------------- /doc/epydoc-slides.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nltk/epydoc/HEAD/doc/epydoc-slides.pdf -------------------------------------------------------------------------------- /doc/epydoc-slides.ppt: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nltk/epydoc/HEAD/doc/epydoc-slides.ppt -------------------------------------------------------------------------------- /doc/home.thumbnail.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nltk/epydoc/HEAD/doc/home.thumbnail.png -------------------------------------------------------------------------------- /doc/index.thumbnail.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nltk/epydoc/HEAD/doc/index.thumbnail.png -------------------------------------------------------------------------------- /doc/pysrc.thumbnail.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nltk/epydoc/HEAD/doc/pysrc.thumbnail.png -------------------------------------------------------------------------------- /doc/uml.thumbnail.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nltk/epydoc/HEAD/doc/uml.thumbnail.png -------------------------------------------------------------------------------- /doc/epydoc_guiconfig.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nltk/epydoc/HEAD/doc/epydoc_guiconfig.png -------------------------------------------------------------------------------- /src/scripts/epydocgui: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | # 3 | # Call the graphical interface for Epydoc. 4 | # 5 | 6 | from epydoc.gui import gui 7 | gui() 8 | -------------------------------------------------------------------------------- /src/MANIFEST.in: -------------------------------------------------------------------------------- 1 | include LICENSE.txt 2 | include README.txt 3 | recursive-include doc *.html *.css *.png 4 | recursive-include man *.1 5 | include scripts/* 6 | include Makefile 7 | -------------------------------------------------------------------------------- /src/epydoc/docwriter/__init__.py: -------------------------------------------------------------------------------- 1 | # epydoc -- Output generation 2 | # 3 | # Copyright (C) 2005 Edward Loper 4 | # Author: Edward Loper 5 | # URL: 6 | # 7 | # $Id: __init__.py 956 2006-03-10 01:30:51Z edloper $ 8 | 9 | """ 10 | Output generation. 11 | """ 12 | __docformat__ = 'epytext en' 13 | -------------------------------------------------------------------------------- /src/scripts/epydoc: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | # 3 | # Call the command line interface for Epydoc. 4 | # 5 | 6 | # Make sure that we don't get confused between an epydoc.py script and 7 | # the real epydoc package. 8 | import sys, os.path 9 | if os.path.exists(os.path.join(sys.path[0], 'epydoc.py')): 10 | del sys.path[0] 11 | 12 | from epydoc.cli import cli 13 | cli() 14 | 15 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Editor junk 2 | *.swp 3 | *.bkp 4 | *.bak 5 | *~ 6 | 7 | # Files generated by build system 8 | /.api-html.up2date 9 | /.examples.up2date 10 | /html/ 11 | /profile.out 12 | 13 | # Pipenv, setuptools, etc. 14 | /pipenv 15 | .venv/ 16 | /dist/ 17 | /build/ 18 | /wheelhouse/ 19 | /epydoc-* 20 | *.egg-info 21 | *.tox 22 | *.deb 23 | /MANIFEST 24 | 25 | # Python generated stuff 26 | *.py[cod] 27 | __pycache__ 28 | 29 | 30 | # vim: set syntax=conf tabstop=2 expandtab nospell: 31 | -------------------------------------------------------------------------------- /src/scripts/epydoc.pyw: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | # 3 | # Call the graphical interface for Epydoc. 4 | # 5 | 6 | # We have to do some path magic to prevent Python from getting 7 | # confused about the difference between this epydoc module, and the 8 | # real epydoc package. So sys.path[0], which contains the directory 9 | # of the script. 10 | import sys, os.path 11 | script_path = os.path.abspath(sys.path[0]) 12 | sys.path = [p for p in sys.path if 13 | os.path.abspath(p) != script_path] 14 | 15 | from epydoc.gui import gui 16 | gui() 17 | 18 | -------------------------------------------------------------------------------- /src/scripts/epydoc.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | # 3 | # Call the command line interface for Epydoc. 4 | # 5 | 6 | # We have to do some path magic to prevent Python from getting 7 | # confused about the difference between this epydoc module, and the 8 | # real epydoc package. So remove sys.path[0], which contains the 9 | # directory of the script. 10 | import sys, os.path 11 | script_path = os.path.abspath(sys.path[0]) 12 | sys.path = [p for p in sys.path if 13 | os.path.abspath(p) != script_path] 14 | 15 | from epydoc.cli import cli 16 | cli() 17 | 18 | -------------------------------------------------------------------------------- /doc/epytext_example.py: -------------------------------------------------------------------------------- 1 | # 2 | # epytext_example.py 3 | # 4 | # Example code used by the epytext manual. 5 | # 6 | # These functions are used by epytextintro.html to illustrate epytext, 7 | # and show what output is generated by epydoc for a simple docstring. 8 | # 9 | """ 10 | Examples for the epytext manual. 11 | """ 12 | __docformat__='epytext' 13 | 14 | def x_intercept(m, b): 15 | """ 16 | Return the x intercept of the line M{y=m*x+b}. The X{x intercept} 17 | of a line is the point at which it crosses the x axis (M{y=0}). 18 | 19 | This function can be used in conjuction with L{z_transform} to 20 | find an arbitrary function's zeros. 21 | 22 | @type m: number 23 | @param m: The slope of the line. 24 | @type b: number 25 | @param b: The y intercept of the line. The X{y intercept} of a 26 | line is the point at which it crosses the y axis (M{x=0}). 27 | @rtype: number 28 | @return: the x intercept of the line M{y=m*x+b}. 29 | """ 30 | return -b/m 31 | 32 | def z_transform(f): 33 | """ 34 | This is just an example; there is no z_transform function. 35 | """ 36 | return f(12) 37 | 38 | -------------------------------------------------------------------------------- /src/epydoc/test/py2/zope3.doctest: -------------------------------------------------------------------------------- 1 | Regression Testing for Zope 3 support 2 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3 | :RequireModule: zope.interface 4 | 5 | >>> from epydoc.test.util import runintrospecter 6 | 7 | We treat zope interface objects as if they were classes: 8 | 9 | >>> runintrospecter(s=''' 10 | ... from zope.interface import Interface, Attribute 11 | ... class IExample(Interface): 12 | ... """This interface represents a generic example.""" 13 | ... 14 | ... text = Attribute("The text of the example") 15 | ... 16 | ... def setText(text): 17 | ... "This method writes the passed text to the text attribute." 18 | ... 19 | ... def getText(): 20 | ... "This method returns the value of the text attribute." 21 | ... ''', attribs='pyval canonical_name', introspect='IExample') 22 | ClassDoc for epydoc_test.IExample [0] 23 | +- canonical_name = DottedName('epydoc_test', 'IExample') 24 | +- pyval = 25 | 26 | (If we didn't add special support, ``IExample`` would be a 27 | `GenericValueDoc`.) 28 | -------------------------------------------------------------------------------- /src/epydoc/test/py3/zope3.doctest: -------------------------------------------------------------------------------- 1 | Regression Testing for Zope 3 support 2 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3 | :RequireModule: zope.interface 4 | 5 | >>> from epydoc.test.util import runintrospecter 6 | 7 | We treat zope interface objects as if they were classes: 8 | 9 | >>> runintrospecter(s=''' 10 | ... from zope.interface import Interface, Attribute 11 | ... class IExample(Interface): 12 | ... """This interface represents a generic example.""" 13 | ... 14 | ... text = Attribute("The text of the example") 15 | ... 16 | ... def setText(text): 17 | ... "This method writes the passed text to the text attribute." 18 | ... 19 | ... def getText(): 20 | ... "This method returns the value of the text attribute." 21 | ... ''', attribs='pyval canonical_name', introspect='IExample') 22 | ClassDoc for epydoc_test.IExample [0] 23 | +- canonical_name = DottedName('epydoc_test', 'IExample') 24 | +- pyval = 25 | 26 | (If we didn't add special support, ``IExample`` would be a 27 | `GenericValueDoc`.) 28 | -------------------------------------------------------------------------------- /doc/rst-template.txt: -------------------------------------------------------------------------------- 1 | %(head_prefix)s 2 | %(head)s 3 | %(stylesheet)s 4 | %(body_prefix)s 5 | %(body_pre_docinfo)s 6 | %(docinfo)s 7 | %(body)s 8 | 9 | 10 | 11 | 12 | 15 | 16 | 19 | 20 | 23 | 24 | 27 | 33 | 34 |
13 | 14 | Home 17 | 18 | Installing Epydoc 21 | 22 | Using Epydoc 25 | 26 | Epytext 28 | 29 | 30 | SourceForge
35 | 36 | 37 | -------------------------------------------------------------------------------- /src/LICENSE.txt: -------------------------------------------------------------------------------- 1 | epydoc is released under the following license: 2 | 3 | Permission is hereby granted, free of charge, to any person 4 | obtaining a copy of this software and any associated documentation 5 | files (the "Software"), to deal in the Software without 6 | restriction, including without limitation the rights to use, copy, 7 | modify, merge, publish, distribute, sublicense, and/or sell copies 8 | of the Software, and to permit persons to whom the Software is 9 | furnished to do so, subject to the following conditions: 10 | 11 | The above copyright notice and this permission notice shall be 12 | included in all copies or substantial portions of the Software. 13 | 14 | The software is provided "as is", without warranty of any 15 | kind, express or implied, including but not limited to the 16 | warranties of merchantability, fitness for a particular purpose 17 | and noninfringement. In no event shall the authors or copyright 18 | holders be liable for any claim, damages or other liability, 19 | whether in an action of contract, tort or otherwise, arising from, 20 | out of or in connection with the software or the use or other 21 | dealings in the software. 22 | -------------------------------------------------------------------------------- /doc/rst-template2.txt: -------------------------------------------------------------------------------- 1 | %(head_prefix)s 2 | %(head)s 3 | %(stylesheet)s 4 | %(body_prefix)s 5 | %(body_pre_docinfo)s 6 | %(docinfo)s 7 | %(body)s 8 | 9 | 10 | 11 | 12 | 15 | 16 | 19 | 20 | 23 | 24 | 27 | 33 | 34 |
13 | 14 | Home 17 | 18 | Installing Epydoc 21 | 22 | Using Epydoc 25 | 26 | Epytext 28 | 29 | 30 | SourceForge
35 | 36 | 37 | -------------------------------------------------------------------------------- /src/scripts/apirst2html.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | # -*- coding: iso-8859-1 -*- 3 | 4 | """An HTML writer supporting link to external documentation. 5 | 6 | This module is a frontend for the Docutils_ HTML writer. It allows a document 7 | to reference objects documented in the API documentation generated by 8 | extraction tools such as Doxygen_ or Epydoc_. 9 | 10 | .. _Docutils: http://docutils.sourceforge.net/ 11 | .. _Doxygen: http://www.doxygen.org/ 12 | .. _Epydoc: http://epydoc.sourceforge.net/ 13 | """ 14 | 15 | # $Id: apirst2html.py 1531 2007-02-18 23:07:25Z dvarrazzo $ 16 | __version__ = "$Revision: 1531 $"[11:-2] 17 | __author__ = "Daniele Varrazzo" 18 | __copyright__ = "Copyright (C) 2007 by Daniele Varrazzo" 19 | __docformat__ = 'reStructuredText en' 20 | 21 | try: 22 | import locale 23 | locale.setlocale(locale.LC_ALL, '') 24 | except: 25 | pass 26 | 27 | # We have to do some path magic to prevent Python from getting 28 | # confused about the difference between the ``epydoc.py`` script, and the 29 | # real ``epydoc`` package. So remove ``sys.path[0]``, which contains the 30 | # directory of the script. 31 | import sys, os.path 32 | script_path = os.path.abspath(sys.path[0]) 33 | sys.path = [p for p in sys.path if os.path.abspath(p) != script_path] 34 | 35 | import epydoc.docwriter.xlink as xlink 36 | 37 | from docutils.core import publish_cmdline, default_description 38 | description = ('Generates (X)HTML documents with API documentation links. ' 39 | + default_description) 40 | publish_cmdline(reader=xlink.ApiLinkReader(), writer_name='html', 41 | description=description) 42 | -------------------------------------------------------------------------------- /doc/inh_example.py: -------------------------------------------------------------------------------- 1 | # 2 | # inh_example.py 3 | # 4 | # Example code used by the epytext manual. 5 | # 6 | # These classes are used to illustrate the different inheritance 7 | # styles. (grouped, listed, and included). 8 | # 9 | """ 10 | Examples for the epytext manual. 11 | """ 12 | __docformat__='epytext' 13 | 14 | class Animal: 15 | def eat(self, food): "Consume the given food object." 16 | def sleep(self, time): "Sleep for the given period of time." 17 | 18 | class Bug(Animal): 19 | def infest(self, code): "Add new bugs to the given program." 20 | def hide(self): 21 | """ 22 | Temporarily stop breaking a program, in order to evade 23 | capture. 24 | """ 25 | class Bird(Animal): 26 | def fly(self, dest): "Fly to the given destination." 27 | 28 | class Fish(Animal): 29 | def swim(self, dest): "Swim to the given destination." 30 | 31 | class Mammal(Animal): 32 | def run(self, dest): "Run to the given destination." 33 | 34 | class Primate(Mammal): 35 | def climb(self, tree): "Climb up the given tree." 36 | def grab(self, object): "Grab hold of the given object." 37 | 38 | class Human(Primate): 39 | def talk(self, animal): 40 | """ 41 | Talk to the given animal. Depending on what kind of creature 42 | C{animal} is, it may or may not be responsive. 43 | """ 44 | 45 | class Programmer(Human): 46 | def hack(self, code): "Improve the given program." 47 | def squish(self, bug, code): 48 | """ 49 | Remove the given bug from the given program. 50 | @type bug: L{Bug} 51 | @param bug: The bug that should be removed from C{code}. 52 | """ 53 | 54 | -------------------------------------------------------------------------------- /doc/manual.txt: -------------------------------------------------------------------------------- 1 | ================== 2 | Epydoc 3 | ================== 4 | ------------------------------------------------- 5 | Automatic API Documentation Generation for Python 6 | ------------------------------------------------- 7 | 8 | .. $Id: manual.txt 1559 2007-02-27 06:42:46Z edloper $ 9 | 10 | :Author: `Edward Loper `__ 11 | 12 | :Version: 3.0b1 13 | 14 | :Abstract: 15 | Epydoc is a tool for generating API documentation for Python modules, 16 | based on their docstrings. For an example of epydoc's output, see the API 17 | documentation for epydoc itself (html_, pdf_). A lightweight markup language 18 | called epytext_ can be used to format docstrings, and to add information 19 | about specific fields, such as parameters and instance variables. Epydoc 20 | also understands docstrings written in reStructuredText_, Javadoc_, and 21 | plaintext. For a more extensive example of epydoc's output, see the `API 22 | documentation for Python 2.4`_. 23 | 24 | .. _html: http://epydoc.sourceforge.net/api/ 25 | .. _pdf: http://epydoc.sourceforge.net/epydoc.pdf 26 | .. _epytext: `The Epytext Markup Language`_ 27 | .. _reStructuredText: 28 | http://docutils.sourceforge.net/rst.html 29 | .. _JavaDoc: http://java.sun.com/j2se/javadoc/ 30 | .. _API documentation for Python 2.4: 31 | http://epydoc.sourceforge.net/stdlib/ 32 | 33 | .. contents:: 34 | .. section-numbering:: 35 | 36 | 37 | .. Include the document chapters 38 | 39 | .. include:: manual-install.txt 40 | .. include:: manual-usage.txt 41 | .. include:: manual-docstring.txt 42 | .. include:: manual-epytext.txt 43 | .. include:: manual-fields.txt 44 | .. include:: manual-othermarkup.txt 45 | .. include:: manual-reference.txt 46 | -------------------------------------------------------------------------------- /src/epydoc/test/javadoc.doctest: -------------------------------------------------------------------------------- 1 | Regression Testing for javadoc 2 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3 | >>> from epydoc.test.util import print_warnings 4 | >>> print_warnings() 5 | 6 | Summary 7 | ======= 8 | The implementation of the summaization function works as expected. 9 | 10 | >>> from epydoc.markup import javadoc 11 | >>> def getsummary(s): 12 | ... p = javadoc.parse_docstring(s, []) 13 | ... s, o = p.summary() 14 | ... s = s.to_plaintext(None).strip() 15 | ... return s, o 16 | 17 | #Let's not lose anything! 18 | 19 | >>> getsummary("Single line") 20 | ('Single line', False) 21 | 22 | >>> getsummary("Single line.") 23 | ('Single line.', False) 24 | 25 | >>> getsummary(""" 26 | ... Single line with period. 27 | ... """) 28 | ('Single line with period.', False) 29 | 30 | >>> getsummary(""" 31 | ... Single line with period. 32 | ... 33 | ... @type Also with a tag. 34 | ... """) 35 | ('Single line with period.', False) 36 | 37 | >>> getsummary(""" 38 | ... Other lines with period. 39 | ... This is attached 40 | ... """) 41 | ('Other lines with period.', True) 42 | 43 | >>> getsummary(""" 44 | ... Other lines with period. 45 | ... 46 | ... This is detached 47 | ... 48 | ... @type Also with a tag. 49 | ... """) 50 | ('Other lines with period.', True) 51 | 52 | >>> getsummary(""" 53 | ... Other lines without period 54 | ... This is attached 55 | ... """) 56 | ('Other lines without period...', True) 57 | 58 | >>> getsummary(""" 59 | ... Other lines without period 60 | ... 61 | ... This is detached 62 | ... """) 63 | ('Other lines without period...', True) 64 | 65 | >>> getsummary(""" 66 | ... Single line without period 67 | ... 68 | ... @type Also with a tag. 69 | ... """) 70 | ('Single line without period', False) 71 | -------------------------------------------------------------------------------- /src/tools/mkdispatch.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | # -*- coding: iso-8859-1 -*- 3 | """A tool to allow creation of both single page and multi-page manual. 4 | 5 | For each file name in argv, detect title names and print a directive 6 | referring to it as anchor in an html file. 7 | """ 8 | 9 | from __future__ import absolute_import 10 | from __future__ import print_function 11 | 12 | # $Id: mkdispatch.py 1771 2008-02-24 03:42:42Z edloper $ 13 | __version__ = "$Revision: 1771 $"[11:-2] 14 | __author__ = "Daniele Varrazzo" 15 | __copyright__ = "Copyright (C) 2007 by Daniele Varrazzo" 16 | 17 | import sys, os 18 | 19 | def parse_pairs(fn): 20 | """Parse a file and return a list of directives to create links.""" 21 | outfile = os.path.splitext(os.path.split(fn)[1])[0] + '.html' 22 | rv = [] 23 | prev = None 24 | for curr in open(fn): 25 | curr = curr.rstrip() 26 | if prev is not None: 27 | if curr and curr[0] in "'^-=~": 28 | if curr == curr[0] * len(curr): 29 | rv.append(".. _%s: %s#%s" % 30 | (prev, outfile, get_anchor(prev))) 31 | prev = curr 32 | 33 | return rv 34 | 35 | import string 36 | charmap = {} 37 | charmap.update(zip(string.ascii_lowercase, string.ascii_lowercase)) 38 | charmap.update(zip(string.ascii_uppercase, string.ascii_lowercase)) 39 | charmap[' '] = '-' 40 | for k in '()': 41 | charmap[k] = '' 42 | 43 | def get_anchor(s): 44 | # IndexErrors are expected to test for what else include in the map 45 | try: 46 | return "".join(map(charmap.__getitem__, s)) 47 | except KeyError as e: 48 | sys.stderr.write('Unexpected char while getting anchor for %r: %s\n' 49 | % (s, e)) 50 | sys.exit(-1) 51 | 52 | if __name__ == '__main__': 53 | for fn in sys.argv[1:]: 54 | for dir in parse_pairs(fn): 55 | print(dir) 56 | 57 | -------------------------------------------------------------------------------- /src/epydoc/test/plaintext.doctest: -------------------------------------------------------------------------------- 1 | Regression Testing for plaintext 2 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3 | >>> from epydoc.test.util import print_warnings 4 | >>> print_warnings() 5 | 6 | Summary 7 | ======= 8 | The implementation of the summaization function works as expected. 9 | 10 | >>> from epydoc.markup import plaintext 11 | >>> def getsummary(s): 12 | ... p = plaintext.parse_docstring(s, []) 13 | ... s, o = p.summary() 14 | ... s = s.to_plaintext(None).strip() 15 | ... return s, o 16 | 17 | Let's not lose anything! 18 | 19 | >>> getsummary("Single line") 20 | ('Single line', False) 21 | 22 | >>> getsummary("Single line.") 23 | ('Single line.', False) 24 | 25 | >>> getsummary(""" 26 | ... Single line with period. 27 | ... """) 28 | ('Single line with period.', False) 29 | 30 | >>> getsummary(""" 31 | ... Other lines with period. 32 | ... This is attached 33 | ... """) 34 | ('Other lines with period.', True) 35 | 36 | >>> getsummary(""" 37 | ... Other lines with period. 38 | ... 39 | ... This is detached 40 | ... """) 41 | ('Other lines with period.', True) 42 | 43 | >>> getsummary(""" 44 | ... Other lines without period 45 | ... This is attached 46 | ... """) 47 | ('Other lines without period...', True) 48 | 49 | >>> getsummary(""" 50 | ... Other lines without period 51 | ... 52 | ... This is detached 53 | ... """) 54 | ('Other lines without period...', True) 55 | 56 | In 3.0beta1 docstrings such this were not correctly summarized. 57 | 58 | >>> getsummary("""A user-defined wrapper around string objects 59 | ... 60 | ... Note: string objects have grown methods in Python 1.6 61 | ... This module requires Python 1.6 or later. 62 | ... """) 63 | ('A user-defined wrapper around string objects', True) 64 | 65 | >>> getsummary("""This is more tricky 66 | ... than the test before 67 | ... 68 | ... but i am looking for the same bug. 69 | ... """) 70 | ('This is more tricky\nthan the test before', True) 71 | -------------------------------------------------------------------------------- /src/README.txt: -------------------------------------------------------------------------------- 1 | ############################################################### 2 | ### Epydoc ### 3 | ###~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~### 4 | ### Copyright (C) Edward Loper ### 5 | ### Author: Edward Loper ### 6 | ### URL: ### 7 | ### For license information, see LICENSE.TXT ### 8 | ############################################################### 9 | 10 | Introduction 11 | ~~~~~~~~~~~~ 12 | Epydoc is a tool for generating API documentation for Python 13 | modules, based on their docstrings. A lightweight markup language 14 | called epytext can be used to format docstrings, and to add 15 | information about specific fields, such as parameters and instance 16 | variables. 17 | 18 | Documentation 19 | ~~~~~~~~~~~~~ 20 | Documentation for epydoc, including installation and usage 21 | instructions, and a complete description of the epytext markup 22 | language, is available on the epydoc homepage: 23 | 24 | 25 | 26 | This documentation is also available in the doc/ subdirectory of 27 | the source distribution. 28 | 29 | Installing 30 | ~~~~~~~~~~ 31 | To install epydoc, use make: 32 | 33 | [user epydoc-3.0]$ su 34 | Password: 35 | [root epydoc-3.0]# make install 36 | [root epydoc-3.0]# make installdocs 37 | 38 | Or use the distutils setup.py script: 39 | 40 | [user epydoc-3.0]$ su 41 | Password: 42 | [root epydoc-3.0]# python setup.py install 43 | 44 | For complete installation instructions, including instructions on 45 | how to install from RPM package, Debian package, or the windows 46 | installer, see the epydoc homepage: 47 | 48 | 49 | 50 | Usage 51 | ~~~~~ 52 | Run "epydoc --help" for a description of epydoc's usage. 53 | 54 | Contributing 55 | ~~~~~~~~~~~~ 56 | If you are interested in contributing to epydoc, please email 57 | . 58 | -------------------------------------------------------------------------------- /doc/future.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | Epydoc: Future Directions 4 | 5 | 6 | 7 | 8 | 9 |
10 |

Epydoc: Future Directions

11 | 12 |

Short Term

13 |

Epydoc version 3.0 is currently in alpha release. My current 14 | plans for the near future include:

15 | 16 |
    17 |
  • Improve support for graph generation.
    • 18 |
  • Work on plaintext output.
    • 19 |
  • Profiling
    • 20 |
  • More regression tests
    • 21 |
  • Add support for generating indices of bugs, todo items, 22 | etc.
    • 23 |
  • Add an @ingroup tag. 24 |
  • Release epydoc 3.0.
    • 25 |
26 | 27 |

Long Term

28 |

Things I'd eventually like to see in epydoc include:

29 | 30 |
    31 |
  • Change the epytext parser to use simple classes instead 32 | of DOM.
    • 33 |
  • Output to man (troff)?
    • 34 |
  • Output to docbook or directly to pdf?
    • 35 |
36 | 37 |
38 | 39 | 40 | 41 | 44 | 45 | 48 | 49 | 52 | 53 | 56 | 62 | 63 |
42 | 43 | Home 46 | 47 | Installing Epydoc 50 | 51 | Using Epydoc 54 | 55 | Epytext 57 | 58 | 59 | SourceForge
64 | 65 | 66 | -------------------------------------------------------------------------------- /src/epydoc/test/cli.doctest: -------------------------------------------------------------------------------- 1 | Regression Testing for epydoc.cli 2 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3 | 4 | A helper function to check the behavior of parse_arguments: 5 | 6 | >>> import sys, epydoc.cli 7 | >>> from epydoc.seven import six 8 | >>> def parse_arguments(argv): 9 | ... defaults = epydoc.cli.option_defaults() 10 | ... if isinstance(argv, six.string_types): argv = argv.split() 11 | ... sys.argv = list(argv) 12 | ... options = epydoc.cli.parse_arguments() 13 | ... for opt, val in sorted(options.__dict__.items()): 14 | ... if val != defaults.get(opt): 15 | ... if isinstance(val, dict): 16 | ... val = '{%s}' % ', '.join(sorted( 17 | ... ['%r: %r' % pair for pair in val.items()])) 18 | ... print('%20s: %s' % (opt, val)) 19 | 20 | Basic test: 21 | >>> parse_arguments('epydoc sys') 22 | names: ['sys'] 23 | 24 | The -o option now sets the default_target option if it comes *before* 25 | any action values: 26 | 27 | >>> parse_arguments('epydoc -o foo sys') 28 | default_target: foo 29 | names: ['sys'] 30 | >>> parse_arguments('epydoc -o foo --html sys') 31 | actions: ['html'] 32 | default_target: foo 33 | names: ['sys'] 34 | 35 | But it modifies the target option if it comes *after* any action 36 | values. This allows the user to specify an output location for each 37 | action: 38 | 39 | >>> parse_arguments('epydoc --html -o foo sys') 40 | actions: ['html'] 41 | names: ['sys'] 42 | target: {'html': 'foo'} 43 | 44 | >>> parse_arguments('epydoc --html -o myhtml --pdf -o mypdf sys') 45 | actions: ['html', 'pdf'] 46 | names: ['sys'] 47 | target: {'html': 'myhtml', 'pdf': 'mypdf'} 48 | 49 | The user can specify a default and then override it for select output 50 | formats: 51 | 52 | >>> parse_arguments('epydoc -o foo --pdf --dvi -o bar.dvi --html sys') 53 | actions: ['pdf', 'dvi', 'html'] 54 | default_target: foo 55 | names: ['sys'] 56 | target: {'dvi': 'bar.dvi'} 57 | 58 | -------------------------------------------------------------------------------- /src/epydoc/test/py2/zope2.doctest: -------------------------------------------------------------------------------- 1 | Regression Testing for Zope 2 support 2 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3 | :RequireModule: ExtensionClass 4 | 5 | >>> from epydoc.test.util import runintrospecter 6 | 7 | We treat extension classes as if they were classes: 8 | 9 | >>> from ExtensionClass import ExtensionClass 10 | 11 | >>> runintrospecter(s=''' 12 | ... from ExtensionClass import ExtensionClass 13 | ... ''', attribs='variables value pyval', 14 | ... introspect='ExtensionClass') 15 | ClassDoc [0] 16 | +- pyval = VariableDoc for __basicnew__ [1] 19 | | +- value 20 | | +- RoutineDoc [2] 21 | | +- pyval = 22 | +- __call__ => VariableDoc for __call__ [3] 23 | | +- value 24 | | +- RoutineDoc [4] 25 | | +- pyval = 26 | +- __delattr__ => VariableDoc for __delattr__ [5] 27 | | +- value 28 | | +- RoutineDoc [6] 29 | | +- pyval = 30 | +- __getattr__ => VariableDoc for __getattr__ [7] 31 | | +- value 32 | | +- RoutineDoc [8] 33 | | +- pyval = 34 | +- __init__ => VariableDoc for __init__ [9] 35 | | +- value 36 | | +- RoutineDoc [10] 37 | | +- pyval = 38 | +- __reduce__ => VariableDoc for __reduce__ [11] 39 | | +- value 40 | | +- RoutineDoc [12] 41 | | +- pyval = 42 | +- __repr__ => VariableDoc for __repr__ [13] 43 | | +- value 44 | | +- RoutineDoc [14] 45 | | +- pyval = 46 | +- __setattr__ => VariableDoc for __setattr__ [15] 47 | | +- value 48 | | +- RoutineDoc [16] 49 | | +- pyval = 50 | +- inheritedAttribute => VariableDoc for inheritedAttribute [17] 51 | +- value 52 | +- RoutineDoc [18] 53 | +- pyval = 54 | 55 | (If we didn't add special support, ``ExtensionClass`` would be a 56 | `GenericValueDoc`.) 57 | 58 | -------------------------------------------------------------------------------- /src/epydoc/test/py3/zope2.doctest: -------------------------------------------------------------------------------- 1 | Regression Testing for Zope 2 support 2 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3 | :RequireModule: ExtensionClass 4 | 5 | >>> from epydoc.test.util import runintrospecter 6 | 7 | We treat extension classes as if they were classes: 8 | 9 | >>> from ExtensionClass import ExtensionClass 10 | 11 | >>> runintrospecter(s=''' 12 | ... from ExtensionClass import ExtensionClass 13 | ... ''', attribs='variables value pyval', 14 | ... introspect='ExtensionClass') 15 | ClassDoc [0] 16 | +- pyval = VariableDoc for __basicnew__ [1] 19 | | +- value 20 | | +- RoutineDoc [2] 21 | | +- pyval = 22 | +- __call__ => VariableDoc for __call__ [3] 23 | | +- value 24 | | +- RoutineDoc [4] 25 | | +- pyval = 26 | +- __delattr__ => VariableDoc for __delattr__ [5] 27 | | +- value 28 | | +- RoutineDoc [6] 29 | | +- pyval = 30 | +- __getattr__ => VariableDoc for __getattr__ [7] 31 | | +- value 32 | | +- RoutineDoc [8] 33 | | +- pyval = 34 | +- __init__ => VariableDoc for __init__ [9] 35 | | +- value 36 | | +- RoutineDoc [10] 37 | | +- pyval = 38 | +- __reduce__ => VariableDoc for __reduce__ [11] 39 | | +- value 40 | | +- RoutineDoc [12] 41 | | +- pyval = 42 | +- __repr__ => VariableDoc for __repr__ [13] 43 | | +- value 44 | | +- RoutineDoc [14] 45 | | +- pyval = 46 | +- __setattr__ => VariableDoc for __setattr__ [15] 47 | | +- value 48 | | +- RoutineDoc [16] 49 | | +- pyval = 50 | +- inheritedAttribute => VariableDoc for inheritedAttribute [17] 51 | +- value 52 | +- RoutineDoc [18] 53 | +- pyval = 54 | 55 | (If we didn't add special support, ``ExtensionClass`` would be a 56 | `GenericValueDoc`.) 57 | 58 | -------------------------------------------------------------------------------- /src/epydoc/seven.py: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2018 Pawel Tomulik 2 | # 3 | # Permission is hereby granted, free of charge, to any person obtaining a copy 4 | # of this software and associated documentation files (the "Software"), to deal 5 | # in the Software without restriction, including without limitation the rights 6 | # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 7 | # copies of the Software, and to permit persons to whom the Software is 8 | # furnished to do so, subject to the following conditions: 9 | # 10 | # The above copyright notice and this permission notice shall be included in all 11 | # copies or substantial portions of the Software. 12 | # 13 | # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 14 | # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 15 | # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 16 | # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 17 | # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 18 | # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 19 | # SOFTWARE. 20 | 21 | """Epydoc extensions to six module""" 22 | 23 | from __future__ import absolute_import 24 | 25 | __author__ = "Pawel Tomulik " 26 | __version__ = "0.0.1" 27 | 28 | from epydoc import six 29 | 30 | import textwrap 31 | 32 | if six.PY3: 33 | def get_method_class(method): 34 | self = six.get_method_self(method) 35 | if self is not None: 36 | return self.__class__ 37 | return None 38 | 39 | def cmp(a, b): 40 | return (a > b) - (a < b) 41 | 42 | exceptions = six.moves.builtins 43 | else: 44 | def get_method_class(method): 45 | return method.im_class 46 | import exceptions 47 | 48 | if six.binary_type is not str: 49 | def xdedent(s, *args): 50 | if isinstance(s, six.binary_type): 51 | s = s.decode(*args) 52 | s = textwrap.dedent(s) 53 | s = s.encode(*args) 54 | else: 55 | s = textwrap.dedent(s) 56 | return s 57 | else: 58 | 59 | def xdedent(s, *args): 60 | return textwrap.dedent(s) 61 | 62 | 63 | six.get_method_class = get_method_class 64 | six.xdedent = xdedent 65 | six.cmp = cmp 66 | six.moves.exceptions = exceptions 67 | -------------------------------------------------------------------------------- /src/setup.py: -------------------------------------------------------------------------------- 1 | #! /usr/bin/env python 2 | # 3 | # Edward Loper's API Documentation Generation Tool 4 | # 5 | # Created [05/27/01 09:04 PM] 6 | # Edward Loper 7 | # 8 | 9 | from distutils.core import setup 10 | import re, sys, epydoc 11 | 12 | VERSION = str(epydoc.__version__) 13 | (AUTHOR, EMAIL) = re.match('^(.*?)\s*<(.*)>$', epydoc.__author__).groups() 14 | URL = epydoc.__url__ 15 | LICENSE = epydoc.__license__ 16 | KEYWORDS='docstring restructuredtext rst javadoc docformat pydoc epydoc' 17 | LONG_DESCRIPTION = """\ 18 | Epydoc is a tool for generating API documentation documentation for 19 | Python modules, based on their docstrings. For an example of epydoc's 20 | output, see the API documentation for epydoc itself (`html 21 | `__\ , `pdf 22 | `__\ ). A lightweight markup 23 | language called `epytext `__ 24 | can be used to format docstrings, and to add information about 25 | specific fields, such as parameters and instance variables. Epydoc 26 | also understands docstrings written in `reStructuredText 27 | `__\ , Javadoc, and 28 | plaintext. For a more extensive example of epydoc's output, see the 29 | API documentation for `Python 2.5 30 | `__\ .""" 31 | CLASSIFIERS=[ 32 | 'Development Status :: 5 - Production/Stable', 33 | 'Intended Audience :: Developers', 34 | 'License :: OSI Approved :: MIT License', 35 | 'Programming Language :: Python', 36 | 'Topic :: Documentation', 37 | 'Topic :: Software Development :: Documentation', 38 | ] 39 | 40 | # Classifiers metadata only supported for Python 2.4+ 41 | if sys.version_info[:2] >= (2,4): 42 | other_metadata = dict(classifiers=CLASSIFIERS) 43 | else: 44 | other_metadata = {} 45 | 46 | if '--format=wininst' in sys.argv: 47 | SCRIPTS = ['scripts/epydoc.pyw', 'scripts/epydoc.py'] 48 | else: 49 | SCRIPTS = ['scripts/epydoc', 'scripts/epydocgui'] 50 | 51 | SCRIPTS.append('scripts/apirst2html.py') 52 | 53 | setup(name="epydoc", 54 | description="Edward Loper's API Documentation Generation Tool", 55 | version=VERSION, 56 | author=AUTHOR, 57 | author_email=EMAIL, 58 | license=LICENSE, 59 | url=URL, 60 | scripts=SCRIPTS, 61 | keywords=KEYWORDS.split(), 62 | long_description=LONG_DESCRIPTION, 63 | packages=['epydoc', 'epydoc.markup', 'epydoc.test', 'epydoc.docwriter'], 64 | **other_metadata) 65 | 66 | -------------------------------------------------------------------------------- /doc/license.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | Epydoc License 4 | 5 | 6 | 7 | 8 |
9 |

Epydoc License

10 | 11 |

Epydoc is governed by the MIT open-source license:

12 | 13 |
14 |

Permission is hereby granted, free of charge, to any person 15 | obtaining a copy of this software and any associated 16 | documentation files (the "Software"), to deal in the Software 17 | without restriction, including without limitation the rights 18 | to use, copy, modify, merge, publish, distribute, sublicense, 19 | and/or sell copies of the Software, and to permit persons to 20 | whom the Software is furnished to do so, subject to the 21 | following conditions:

22 | 23 |

The above copyright notice and this permission notice 24 | shall be included in all copies or substantial portions of the 25 | Software.

26 | 27 |

The software is provided "as is", without warranty of any 28 | kind, express or implied, including but not limited to the 29 | warranties of merchantability, fitness for a particular 30 | purpose and noninfringement. In no event shall the authors or 31 | copyright holders be liable for any claim, damages or other 32 | liability, whether in an action of contract, tort or 33 | otherwise, arising from, out of or in connection with the 34 | software or the use or other dealings in the software.

35 |
36 | 37 |
38 | 39 | 40 | 41 | 44 | 45 | 48 | 49 | 52 | 53 | 56 | 62 | 63 |
42 | 43 | Home 46 | 47 | Installing Epydoc 50 | 51 | Using Epydoc 54 | 55 | Epytext 57 | 58 | 59 | SourceForge
64 | 65 | 66 | -------------------------------------------------------------------------------- /src/tools/rst2html.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/python 2 | 3 | r""" 4 | A customized driver for converting docutils reStructuredText documents 5 | into HTML. This is used to generated HTML versions of the regression 6 | files, for the webpage. 7 | """ 8 | 9 | from __future__ import absolute_import 10 | 11 | # Docutils imports 12 | from docutils.core import publish_cmdline, default_description 13 | from docutils.writers.html4css1 import HTMLTranslator, Writer as HTMLWriter 14 | import docutils.nodes 15 | 16 | # Epydoc imports. Make sure path contains the 'right' epydoc. 17 | import sys, os 18 | sys.path.insert(0, '../') 19 | import epydoc.markup.restructuredtext # register the 'python' directive 20 | from epydoc.markup.doctest import doctest_to_html, doctest_to_latex, \ 21 | HTMLDoctestColorizer 22 | 23 | from epydoc.docwriter.xlink import ApiLinkReader 24 | 25 | class CustomizedReader(ApiLinkReader): 26 | settings_defaults = (ApiLinkReader.settings_defaults or {}).copy() 27 | settings_defaults.update({ 28 | 'external_api': [ 'epydoc' ], 29 | 'external_api_root': [ 'epydoc:http://epydoc.sourceforge.net/api/' ], 30 | 'external_api_file': [ 'epydoc:' + os.path.join( 31 | os.path.split(__file__)[0], '../../html/api/api-objects.txt') ], 32 | }) 33 | 34 | class CustomizedHTMLWriter(HTMLWriter): 35 | settings_defaults = (HTMLWriter.settings_defaults or {}).copy() 36 | settings_defaults.update({ 37 | 'stylesheet': 'custom.css', 38 | 'stylesheet_path': None, 39 | 'output_encoding': 'ascii', 40 | 'output_encoding_error_handler': 'xmlcharrefreplace', 41 | 'embed_stylesheet': False, 42 | }) 43 | 44 | def __init__(self): 45 | HTMLWriter.__init__(self) 46 | self.translator_class = CustomizedHTMLTranslator 47 | 48 | class CustomizedHTMLTranslator(HTMLTranslator): 49 | def visit_doctest_block(self, node): 50 | pysrc = node[0].astext() 51 | if node.get('codeblock'): 52 | self.body.append(HTMLDoctestColorizer().colorize_codeblock(pysrc)) 53 | else: 54 | self.body.append(doctest_to_html(pysrc)) 55 | raise docutils.nodes.SkipNode 56 | 57 | description = ('Generates HTML documents from reStructuredText ' 58 | 'documents. ' + default_description) 59 | writer = CustomizedHTMLWriter() 60 | reader = CustomizedReader() 61 | 62 | #this doesn't work. Put ``.. default-role:: epydoc`` in the doctests instead. 63 | #docutils.parsers.rst.roles.DEFAULT_INTERPRETED_ROLE = 'epydoc' 64 | 65 | docutils.core.publish_cmdline(reader=reader, writer=writer, 66 | description=description) 67 | -------------------------------------------------------------------------------- /src/epydoc/markup/plaintext.py: -------------------------------------------------------------------------------- 1 | # 2 | # plaintext.py: plaintext docstring parsing 3 | # Edward Loper 4 | # 5 | # Created [04/10/01 12:00 AM] 6 | # $Id: plaintext.py 1574 2007-03-07 02:55:14Z dvarrazzo $ 7 | # 8 | 9 | """ 10 | Parser for plaintext docstrings. Plaintext docstrings are rendered as 11 | verbatim output, preserving all whitespace. 12 | """ 13 | 14 | from __future__ import absolute_import 15 | 16 | __docformat__ = 'epytext en' 17 | 18 | from epydoc.markup import * 19 | from epydoc.util import plaintext_to_html, plaintext_to_latex 20 | 21 | def parse_docstring(docstring, errors, **options): 22 | """ 23 | @return: A pair C{(M{d}, M{e})}, where C{M{d}} is a 24 | C{ParsedDocstring} that encodes the contents of the given 25 | plaintext docstring; and C{M{e}} is a list of errors that were 26 | generated while parsing the docstring. 27 | @rtype: C{L{ParsedPlaintextDocstring}, C{list} of L{ParseError}} 28 | """ 29 | return ParsedPlaintextDocstring(docstring, **options) 30 | 31 | class ParsedPlaintextDocstring(ParsedDocstring): 32 | def __init__(self, text, **options): 33 | self._verbatim = options.get('verbatim', 1) 34 | if text is None: raise ValueError('Bad text value (expected a str)') 35 | self._text = text 36 | 37 | def to_html(self, docstring_linker, **options): 38 | if options.get('verbatim', self._verbatim) == 0: 39 | return plaintext_to_html(self.to_plaintext(docstring_linker)) 40 | else: 41 | return ParsedDocstring.to_html(self, docstring_linker, **options) 42 | 43 | def to_latex(self, docstring_linker, **options): 44 | if options.get('verbatim', self._verbatim) == 0: 45 | return plaintext_to_latex(self.to_plaintext(docstring_linker)) 46 | else: 47 | return ParsedDocstring.to_latex(self, docstring_linker, **options) 48 | 49 | def to_plaintext(self, docstring_linker, **options): 50 | if 'indent' in options: 51 | indent = options['indent'] 52 | lines = self._text.split('\n') 53 | return '\n'.join([' '*indent+l for l in lines])+'\n' 54 | return self._text+'\n' 55 | 56 | _SUMMARY_RE = re.compile(r'(\s*[\w\W]*?(?:\.(\s|$)|[\n][\t ]*[\n]))') 57 | 58 | def summary(self): 59 | m = self._SUMMARY_RE.match(self._text) 60 | if m: 61 | other = self._text[m.end():] 62 | return (ParsedPlaintextDocstring(m.group(1), verbatim=0), 63 | other != '' and not other.isspace()) 64 | else: 65 | parts = self._text.strip('\n').split('\n', 1) 66 | if len(parts) == 1: 67 | summary = parts[0] 68 | other = False 69 | else: 70 | summary = parts[0] + '...' 71 | other = True 72 | 73 | return ParsedPlaintextDocstring(summary, verbatim=0), other 74 | 75 | # def concatenate(self, other): 76 | # if not isinstance(other, ParsedPlaintextDocstring): 77 | # raise ValueError, 'Could not concatenate docstrings' 78 | # text = self._text+other._text 79 | # options = self._options.copy() 80 | # options.update(other._options) 81 | # return ParsedPlaintextDocstring(text, options) 82 | -------------------------------------------------------------------------------- /src/Makefile: -------------------------------------------------------------------------------- 1 | ############################################################ 2 | ## epydoc Makefile 3 | ## 4 | ## Edward Loper 5 | ############################################################ 6 | 7 | ##////////////////////////////////////////////////////////////////////// 8 | ## Configuration variables 9 | ##////////////////////////////////////////////////////////////////////// 10 | 11 | # Where do man pages and documentation go? 12 | LIB = /usr/share 13 | MAN = ${LIB}/man/ 14 | DOC = ${LIB}/doc/ 15 | 16 | # What version of python to use? 17 | PYTHON = python 18 | 19 | ##////////////////////////////////////////////////////////////////////// 20 | ## Makefile 21 | ##////////////////////////////////////////////////////////////////////// 22 | all: usage 23 | usage: 24 | @echo "Usage:" 25 | @echo " make install -- Install epydoc" 26 | @echo " make installdocs -- Install the documentation for epydoc" 27 | 28 | install: 29 | $(PYTHON) setup.py install 30 | 31 | docs: installdocs 32 | installdocs: 33 | @test -e ${MAN} || \ 34 | echo "Could not find ${MAN}; check the makefile variables." 35 | @test -e ${DOC} || \ 36 | echo "Could not find ${DOC}; check the makefile variables." 37 | @test -e ${MAN} 38 | @test -e ${DOC} 39 | test -e doc || ln -s ../webpage doc 40 | test -e man || ln -s ../man man 41 | cp man/*.1 ${MAN}/man1/ 42 | cp -r doc ${DOC}/epydoc/ 43 | 44 | ##////////////////////////////////////////////////////////////////////// 45 | ## These targets should only be called from 46 | ## the cvs repository (not from distributions). 47 | ##////////////////////////////////////////////////////////////////////// 48 | 49 | # Clean. 50 | # - Erase any pyc and pyo files. 51 | # - Get rid of build/dist directories 52 | clean: 53 | rm -rf build dist MANIFEST 54 | rm -f *.pyc epydoc/*.pyc epydoc/*/*.pyc 55 | rm -f *.pyo epydoc/*.pyo epydoc/*/*.pyo 56 | rm -f doc man 2>/dev/null || true 57 | 58 | # Distributions. 59 | # Build all from scratch; and create links for convenient access. 60 | distributions: clean sdist bdist 61 | 62 | # Source distributions 63 | sdist: gztardist zipdist 64 | 65 | # Built distributions 66 | bdist: rpmdist windist 67 | 68 | # Produce dist/$(NAME)-$(VERSION).tar.gz 69 | gztardist: 70 | test -e doc || ln -s ../webpage doc 71 | test -e man || ln -s ../man man 72 | $(PYTHON) setup.py -q sdist --format=gztar 73 | 74 | # Produce dist/$(NAME)-$(VERSION).tar.gz 75 | zipdist: 76 | test -e doc || ln -s ../webpage doc 77 | test -e man || ln -s ../man man 78 | $(PYTHON) setup.py -q sdist --format=zip 79 | 80 | # Produce dist/$(NAME)-$(VERSION)-1.noarch.rpm 81 | # Produce dist/$(NAME)-$(VERSION)-1.src.rpm 82 | rpmdist: 83 | test -e doc || ln -s ../webpage doc 84 | test -e man || ln -s ../man man 85 | $(PYTHON) setup.py -q bdist --format=rpm 86 | 87 | # Produce dist/$(NAME)-$(VERSION).win32.exe 88 | windist: 89 | test -e doc || ln -s ../webpage doc 90 | test -e man || ln -s ../man man 91 | $(PYTHON) setup.py -q bdist --format=wininst 92 | 93 | upload: 94 | test -e doc || ln -s ../webpage doc 95 | test -e man || ln -s ../man man 96 | $(PYTHON) setup.py register 97 | $(PYTHON) setup.py -q sdist --format=gztar upload 98 | $(PYTHON) setup.py -q sdist --format=zip upload 99 | $(PYTHON) setup.py -q bdist --format=wininst upload 100 | $(PYTHON) setup.py -q bdist --format=rpm upload 101 | 102 | 103 | -------------------------------------------------------------------------------- /doc/doctest/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | Epydoc: Regression Tests 4 | 5 | 6 | 7 | 8 | 9 |
10 |

Epydoc: Regression Tests

11 | 12 |

The following files contain the current regression test suite for 13 | epydoc. Each file contains a prose description of some aspect of 14 | epydoc, interspersed with 15 | doctest 16 | examples. Each of these doctest examples is a single test case.

17 | 18 |
19 |

Regression Tests

20 | 21 |
    22 |
  • APIDoc -- The classes used 23 | to encode API documentation about Python programs.
    • 24 |
  • Introspection -- 25 | Extracting API information about Python objects by directly 26 | introspecting their values.
    • 27 |
  • Source Code Parsing -- 28 | Extracting API information about Python objects by parsing 29 | their source code.
    • 30 |
  • Documentation building -- 31 | Merging different information sources into a single API 32 | hypertext. 33 |
  • Unicode & Encodings -- 34 | Tests for the processing of Python files that use non-ascii 35 | encodings.
    • 36 |
  • Epytext -- Tests for epytext, the default 37 | markup language used by epydoc.
    • 38 |
  • Javadoc -- Tests for epydoc's support 39 | of the Javadoc markup language.
    • 40 |
  • Plaintext -- Tests for epydoc's support 41 | of plaintext markup.
    • 42 |
  • reStructuredText -- Tests 43 | for epydoc's support of the reStructuredText markup language.
    • 44 |
  • Value Representations -- Tests 45 | for epydoc's formatting & syntax highlighting of variable's 46 | values.
    • 47 |
  • Zope 2 -- Tests for epydoc's support 48 | for Zope 2.
    • 49 |
  • Zope 3 -- Tests for epydoc's support 50 | for Zope 3.
    • 51 |
52 |
53 | 54 |
55 | 56 | 57 | 58 | 61 | 62 | 65 | 66 | 69 | 70 | 73 | 79 | 80 |
59 | 60 | Home 63 | 64 | Installing Epydoc 67 | 68 | Using Epydoc 71 | 72 | Epytext 74 | 75 | 76 | SourceForge
81 | 82 | 83 | -------------------------------------------------------------------------------- /doc/history.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | Epydoc History 4 | 5 | 6 | 7 | 8 | 9 |
10 |

Epydoc History

11 | 12 |

I originally became interested in automatic API documentation 13 | extraction tools for Python in March 2002. At the time, there were 14 | several such tools available, including pydoc and HappyDoc. However, none 17 | were widely used. I joined the doc-sig mailing 19 | list, and started working with its members on creating standards 20 | for API documentation tools in Python.

21 | 22 |

I created epydoc as a tool for exploring the issues involved in 23 | writing an automatic API documentation extraction tool. I also 24 | decided to use epydoc to document the Natural Language Toolkit, so 26 | that I would have a fairly large project with which to test out my 27 | system. The markup language and the output of epydoc have changed 28 | many times, and epydoc itself has undergone at least 3 complete 29 | rewrites. But eventually epydoc matured into a more stable 30 | system.

31 | 32 | 39 | 40 |

Significant portions of epydoc were written for version 3.0. This 41 | has allowed me to increase epydoc's functionality in several 42 | significant ways. The most significant change has to do with the way 43 | that epydoc extracts documentation information about python modules. 44 | In previous versions, epydoc extracted information about each module 45 | by importing it, and using introspection to examine its contents. The 46 | new version of epydoc still supports introspection, but is also 47 | capable of extracting information about python modules by parsing 48 | their source code. Furthermore, the new version of epydoc can combine 49 | these two sources of information (introspection & parsing). This is 50 | important because each source has its own advantages and disadvantages 51 | with respect to the other. 52 | 53 |

54 | 55 | 56 | 57 | 60 | 61 | 64 | 65 | 68 | 69 | 72 | 78 | 79 |
58 | 59 | Home 62 | 63 | Installing Epydoc 66 | 67 | Using Epydoc 70 | 71 | Epytext 73 | 74 | 75 | SourceForge
80 | 81 | 82 | -------------------------------------------------------------------------------- /doc/docstrings.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | Python Docstrings 4 | 5 | 6 | 7 | 8 | 9 |
10 |

Python Docstrings

11 | 12 |

Python documentation strings (or docstrings) provide a 13 | convenient way of associating documentation with Python modules, 14 | functions, classes, and methods. An object's docsting is defined by 15 | including a string constant as the first statement in the object's 16 | definition. For example, the following function defines a docstring: 17 |

18 | 19 | 
20 | def x_intercept(m, b):
21 |     """
22 |     Return the x intercept of the line y=m*x+b.  The x intercept of a
23 |     line is the point at which it crosses the x axis (y=0).
24 |     """
25 |     return -b/m
26 |
27 | 28 |

Docstrings can be accessed from the interpreter and from Python 29 | programs using the "__doc__" attribute:

30 | 31 | 
32 | >>> print x_intercept.__doc__
33 |     Return the x intercept of the line y=m*x+b.  The x intercept of a
34 |     line is the point at which it crosses the x axis (y=0).
35 |
36 | 37 |

The pydoc 38 | module, which became part of 40 | the standard library in Python 2.1, can be used to display 41 | information about a Python object, including its docstring:

42 | 43 | 
44 | >>> from pydoc import help
45 | 
46 | >>> help(x_intercept)
47 | Help on function x_intercept in module __main__:
48 | 
49 | x_intercept(m, b)
50 |     Return the x intercept of the line y=m*x+b.  The x intercept of a
51 |     line is the point at which it crosses the x axis (y=0).
52 |
53 | 54 |

For more information about Python docstrings, see the Python 56 | Tutorial or the Oreilly Network article Python 58 | Documentation Tips and Tricks.

59 | 60 |
61 | 62 | 63 | 64 | 67 | 68 | 71 | 72 | 75 | 76 | 79 | 85 | 86 |
65 | 66 | Home 69 | 70 | Installing Epydoc 73 | 74 | Using Epydoc 77 | 78 | Epytext 80 | 81 | 82 | SourceForge
87 | 88 | 89 | -------------------------------------------------------------------------------- /doc/pycon-epydoc.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Epydoc: PyCon 2004 5 | 6 | 7 | 8 |
9 |

Epydoc: PyCon 2004

10 | 11 |

Abstract

12 | 13 |

Epydoc is a tool for generating API documentation for Python 14 | modules, based on their docstrings. It supports several output 15 | formats (including HTML and PDF), and understands four different 16 | markup languages (Epytext, Javadoc, reStructuredText, and plaintext). 17 | A wide variety of fields can be used to supply specific 18 | information about individual objects, such as descriptions of function 19 | parameters, type signatures, and groupings of related objects.

20 | 21 |

Presentation and Paper

22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 34 | 37 | 40 | 43 | 44 | 45 | 48 | 51 | 54 | 57 | 58 | 59 | 62 | 63 | 64 | 65 | 66 |
Video (Quicktime)Audio (MP3)SlidesPaper
32 | Large (Fast DSL) 35 | High Quality (64 kbps) 38 | Acrobat (PDF) 41 | Acrobat (PDF)
46 | Medium (Slow DSL) 49 | Low Quality (16 kbps) 52 | Powerpoint (PPT) 55 | PostScript (PS)
60 | Small (Modem)   
67 | 68 | 69 |

Copyright © 2004 Edward Loper. This work (in all its forms) is 70 | licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 72 | License.

73 | 74 |
75 | 76 | 77 | 78 | 81 | 82 | 85 | 86 | 89 | 90 | 93 | 99 | 100 |
79 | 80 | Home 83 | 84 | Installing Epydoc 87 | 88 | Using Epydoc 91 | 92 | Epytext 94 | 95 | 96 | SourceForge
101 | 102 | 103 | 104 | -------------------------------------------------------------------------------- /doc/epytextintro.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | A Brief Introduction to Epytext 4 | 5 | 6 | 7 | 8 | 9 |
10 |

A Brief Introduction to Epytext

11 | 12 |

Epytext is a simple lightweight markup language that lets you add 13 | formatting and structure to docstrings. Epydoc uses that formatting 14 | and structure to produce nicely formatted API documentation. The 15 | following example (which has an unusually high ratio of documentaiton 16 | to code) illustrates some of the basic features of epytext:

17 | 18 | 
19 | def x_intercept(m, b):
20 |     """
21 |     Return the x intercept of the line M{y=m*x+b}.  The X{x intercept}
22 |     of a line is the point at which it crosses the x axis (M{y=0}).
23 | 
24 |     This function can be used in conjuction with L{z_transform} to
25 |     find an arbitrary function's zeros.
26 | 
27 |     @type  m: number
28 |     @param m: The slope of the line.
29 |     @type  b: number
30 |     @param b: The y intercept of the line.  The X{y intercept} of a
31 |               line is the point at which it crosses the y axis (M{x=0}).
32 |     @rtype:   number
33 |     @return:  the x intercept of the line M{y=m*x+b}.
34 |     """
35 |     return -b/m
36 |
37 | 38 |

You can compare this function definition with the API 40 | documentation generated by epydoc. Note that:

41 | 42 |
    43 |
  • Paragraphs are separated by blank lines.
    • 44 |
  • Inline markup has the form "x{...}", where 45 | "x" is a single capital letter. This example uses 46 | inline markup to mark mathematical expressions 47 | ("M{...}"); terms that should be indexed 48 | ("X{...}"); and links to the documentation of 49 | other objects ("L{...}").
    • 50 |
  • Descriptions of parameters, return values, and types are 51 | marked with "@field:" or 52 | "@field arg:", where 53 | "field" identifies the kind of description, and 54 | "arg" specifies what object is described.
    • 55 |
56 | 57 |

For more information about the epytext markup language, see the epytext manual. Epytext is intentionally very 59 | lightweight. If you wish to use a more expressive markup language, I 60 | recommend reStructuredText.

61 | 62 |
63 | 64 | 65 | 66 | 69 | 70 | 73 | 74 | 77 | 78 | 81 | 87 | 88 |
67 | 68 | Home 71 | 72 | Installing Epydoc 75 | 76 | Using Epydoc 79 | 80 | Epytext 82 | 83 | 84 | SourceForge
89 | 90 | 91 | -------------------------------------------------------------------------------- /src/tools/sty2html.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | # 3 | # Convert epydoc's LaTeX sty files to HTML 4 | 5 | from __future__ import absolute_import 6 | from __future__ import print_function 7 | 8 | from epydoc.docwriter.latex_sty import STYLESHEETS 9 | import re, sys, os.path 10 | 11 | TEMPLATE = """\ 12 | 13 | 15 | 16 | 17 | 18 | %(title)s 19 | 20 | 21 | 22 |
23 |

%(title)s

24 | 
%(body)s
25 |
26 | 27 | 28 | 29 | 32 | 33 | 36 | 37 | 40 | 41 | 44 | 50 | 51 |
30 | 31 | Home 34 | 35 | Installing Epydoc 38 | 39 | Using Epydoc 42 | 43 | Epytext 45 | 46 | 47 | SourceForge
52 | 53 | 54 | """ 55 | 56 | COLOR = {'def': '#705000', 57 | 'defname': '#000080', 58 | 'comment': '#005080', 59 | 'command': '#705000', 60 | 'escape': '#ffffff', 61 | } 62 | COLORIZE_RE = re.compile('|'.join(['(%s)' % s for s in [ 63 | r'(?P(re)?new(command|environment)){(?P[^}]+)}', 64 | r'(?P\\\w+)', 65 | r'(?P\\.)', 66 | r'(?P%.*)', 67 | ]])) 68 | 69 | def subfunc(m): 70 | if m.group('def') is not None: 71 | return ('%s{%s}' % 72 | ('keyword', m.group('def'), 'function', m.group('defname'))) 73 | if m.group('command') is not None: 74 | return '%s' % ('keyword', m.group('command')) 75 | if m.group('escape') is not None: 76 | return '%s' % ('escape', m.group('escape')) 77 | if m.group('comment') is not None: 78 | return '%s' % ('comment', m.group('comment')) 79 | assert False, 'expected to match some group' 80 | 81 | def colorize(s, title): 82 | s = s.replace('&', '&') 83 | s = s.replace('<', '<') 84 | s = s.replace('>', '>') 85 | body = COLORIZE_RE.sub(subfunc, s) 86 | return TEMPLATE % dict(title=title, body=body) 87 | 88 | def main(): 89 | if len(sys.argv) != 2: 90 | print('Usage: %s ' % sys.argv[0]) 91 | sys.exit(-1) 92 | 93 | # hackish to hardcode this; oh well. 94 | sty_list = open('doc/epydoc-style-list.txt', 'w') 95 | sty_list.write('.. This file is automatically generated by %s\n\n' % 96 | sys.argv[0]) 97 | 98 | output_dir = sys.argv[1] 99 | for (name, sheet) in sorted(STYLESHEETS.items()): 100 | if name == 'default': pass 101 | filename = 'epydoc-sty-%s.html' % name 102 | title = 'LaTeX Style File: epydoc-%s.sty' % name 103 | out = open(os.path.join(output_dir, filename), 'wb') 104 | out.write(colorize(sheet, title)) 105 | out.close() 106 | sty_list.write('- `%s <%s>`__\n' % (title, filename)) 107 | 108 | sty_list.close() 109 | 110 | # hackish to hardcode this; oh well. 111 | demo = open('doc/epydoc-latex-demo.tex').read() 112 | out = open(os.path.join(output_dir, 'epydoc-latex-demo.html'), 'wb') 113 | out.write(colorize(demo, 'Epydoc LaTeX Style Reference')) 114 | out.close() 115 | 116 | 117 | if __name__ == '__main__': 118 | main() 119 | -------------------------------------------------------------------------------- /doc/manual-docstring.txt: -------------------------------------------------------------------------------- 1 | Python Docstrings 2 | ================= 3 | 4 | .. $Id: manual-docstring.txt 1575 2007-03-08 21:28:07Z edloper $ 5 | 6 | Python documentation strings (or *docstrings*) provide a convenient way of 7 | associating documentation with Python modules, functions, classes, and methods. 8 | An object's docsting is defined by including a string constant as the first 9 | statement in the object's definition. For example, the following function 10 | defines a docstring: 11 | 12 | .. python:: 13 | 14 | def x_intercept(m, b): 15 | """ 16 | Return the x intercept of the line y=m*x+b. The x intercept of a 17 | line is the point at which it crosses the x axis (y=0). 18 | """ 19 | return -b/m 20 | 21 | Docstrings can be accessed from the interpreter and from Python programs 22 | using the "``__doc__``" attribute: 23 | 24 | .. python:: 25 | 26 | >>> print x_intercept.__doc__ 27 | Return the x intercept of the line y=m*x+b. The x intercept of a 28 | line is the point at which it crosses the x axis (y=0). 29 | 30 | The pydoc_ module, which became part of `the standard library`__ in Python 2.1, 31 | can be used to display information about a Python object, including its 32 | docstring: 33 | 34 | .. _pydoc: http://web.lfw.org/python/pydoc.html 35 | .. __: http://www.python.org/doc/current/lib/module-pydoc.html 36 | 37 | .. python:: 38 | 39 | >>> from pydoc import help 40 | 41 | >>> help(x_intercept) 42 | Help on function x_intercept in module __main__: 43 | 44 | x_intercept(m, b) 45 | Return the x intercept of the line y=m*x+b. The x intercept of a 46 | line is the point at which it crosses the x axis (y=0). 47 | 48 | For more information about Python docstrings, see the `Python Tutorial`__ or 49 | the O'Reilly Network article `Python Documentation Tips and Tricks`__. 50 | 51 | .. __: http://www.python.org/doc/current/tut/node6.html#docstrings 52 | .. __: http://www.onlamp.com/lpt/a/python/2001/05/17/docstrings.html 53 | 54 | 55 | Variable docstrings 56 | ------------------- 57 | 58 | .. 59 | [xx] this should be somewhere else, i guess... 60 | 61 | Python don't support directly docstrings on variables: there is no attribute 62 | that can be attached to variables and retrieved interactively like the 63 | ``__doc__`` attribute on modules, classes and functions. 64 | 65 | While the language doesn't directly provides for them, Epydoc supports 66 | *variable docstrings*: if a variable assignment statement is immediately 67 | followed by a bare string literal, then that assignment is treated as a 68 | docstring for that variable. In classes, variable assignments at the class 69 | definition level are considered class variables; and assignments to instance 70 | variables in the constructor (``__init__``) are considered instance variables: 71 | 72 | .. python:: 73 | 74 | class A: 75 | x = 22 76 | """Docstring for class variable A.x""" 77 | 78 | def __init__(self, a): 79 | self.y = a 80 | """Docstring for instance variable A.y 81 | 82 | Variables may also be documented using *comment docstrings*. If a variable 83 | assignment is immediately preceeded by a comment whose lines begin with the 84 | special marker '``#:``', or is followed on the same line by such a comment, 85 | then it is treated as a docstring for that variable: 86 | 87 | .. python:: 88 | 89 | #: docstring for x 90 | x = 22 91 | x = 22 #: docstring for x 92 | 93 | Notice that variable docstrings are only available for documentation when the 94 | source code is available for *parsing*: it is not possible to retrieve variable 95 | 96 | 97 | Items visibility 98 | ---------------- 99 | 100 | Any Python object (modules, classes, functions, variables...) can be *public* 101 | or *private*. Usually the object name decides the object visibility: objects 102 | whose name starts with an underscore and doesn't end with an underscore are 103 | considered private. All the other objects (including the "magic functions" such 104 | as ``__add__``) are public. 105 | 106 | For each module and class, Epydoc generates pages with both public and private 107 | methods. A Javascript snippet allows you to toggle the visibility of private 108 | objects. 109 | 110 | If a module wants to hide some of the objects it contains (either defined in 111 | the module itself or imported from other modules), it can explicitly list the 112 | names if its `public names`_ in the ``__all__`` variable. 113 | 114 | .. _public names: http://www.python.org/doc/2.4.3/ref/import.html 115 | 116 | If a module defines the ``__all__`` variable, Epydoc uses its content to decide 117 | if the module objects are public or private. 118 | 119 | -------------------------------------------------------------------------------- /src/epydoc/test/__init__.py: -------------------------------------------------------------------------------- 1 | # epydoc -- Regression testing 2 | # 3 | # Copyright (C) 2005 Edward Loper 4 | # Author: Edward Loper 5 | # URL: 6 | # 7 | # $Id: __init__.py 1502 2007-02-14 08:38:44Z edloper $ 8 | 9 | """ 10 | Regression testing. 11 | """ 12 | 13 | from __future__ import absolute_import 14 | from __future__ import print_function 15 | 16 | __docformat__ = 'epytext en' 17 | 18 | import unittest, doctest, epydoc, os, os.path, re, sys 19 | 20 | # Python 2/3 compatibility 21 | from epydoc.seven import six 22 | 23 | def main(): 24 | try: 25 | addflag = doctest.register_optionflag 26 | except: 27 | print("\n" 28 | "The regression test suite requires a more recent version of\n" 29 | "doctest (e.g., the version that ships with Python 2.4 or 2.5).\n" 30 | "Please place a new version of doctest on your path before \n" 31 | "running the test suite.\n") 32 | return 33 | 34 | py_versions = [ 35 | (2, 4), 36 | (2, 5), 37 | (2, 7), 38 | (3, 0), 39 | (3, 4), 40 | (3, 5), 41 | (3, 6), 42 | (3, 7) 43 | ] 44 | 45 | # converts tuple to dotted version string 46 | def t2v(t): return '.'.join([str(x) for x in t]) 47 | 48 | # Define PYTHON#.# and PYMIN#.# option flags 49 | py_min_flags = [ 50 | (addflag('PYTHON%s' % t2v(x)), x) for x in py_versions 51 | ] + [ 52 | (addflag('PYMIN%s' % t2v(x)), x) for x in py_versions 53 | ] 54 | 55 | # Define PYMAX#.# option flags 56 | py_max_flags = [ 57 | (addflag('PYMAX%s' % t2v(x)), x) for x in py_versions 58 | ] 59 | 60 | class DocTestParser(doctest.DocTestParser): 61 | """ 62 | Custom doctest parser that adds support for required-python flags 63 | +PYTHON2.4, +PYTHON2.4, +PYTHON2.7, +PYTHON3.0, etc... 64 | """ 65 | def parse(self, string, name=''): 66 | pieces = doctest.DocTestParser.parse(self, string, name) 67 | for i, val in enumerate(pieces): 68 | if (isinstance(val, doctest.Example) and 69 | not self.py_version_suitable(val)): 70 | pieces[i] = doctest.Example('1', '1') 71 | return pieces 72 | 73 | def py_version_suitable(self, example): 74 | for item in py_min_flags: 75 | if (example.options.get(item[0], False) and 76 | sys.version_info < item[1]): 77 | return False 78 | for item in py_max_flags: 79 | if (example.options.get(item[0], False) and 80 | sys.version_info > item[1]): 81 | return False 82 | return True 83 | 84 | 85 | 86 | # Turn on debugging. 87 | epydoc.DEBUG = True 88 | 89 | # Options for doctest: 90 | options = doctest.ELLIPSIS 91 | doctest.set_unittest_reportflags(doctest.REPORT_UDIFF) 92 | 93 | # Use a custom parser 94 | parser = DocTestParser() 95 | 96 | # Find all test cases. 97 | tests = [] 98 | here = os.path.dirname(__file__) 99 | testdirs = [here, os.path.join(here, 'py2' if six.PY2 else 'py3')] 100 | for testdir in testdirs: 101 | for filename in os.listdir(testdir): 102 | filepath = os.path.join(testdir, filename) 103 | if (filename.endswith('.doctest') and 104 | check_requirements(filepath)): 105 | relpath = os.path.relpath(filepath, here) 106 | tests.append(doctest.DocFileSuite(relpath, 107 | optionflags=options, 108 | parser=parser)) 109 | 110 | # Run all test cases. 111 | unittest.TextTestRunner(verbosity=2).run(unittest.TestSuite(tests)) 112 | 113 | def check_requirements(filename): 114 | """ 115 | Search for strings of the form:: 116 | 117 | [Require: ] 118 | 119 | If any are found, then try importing the module named . 120 | If the import fails, then return False. If all required modules 121 | are found, return True. (This includes the case where no 122 | requirements are listed.) 123 | """ 124 | s = open(filename).read() 125 | for m in re.finditer('(?mi)^[ ]*\:RequireModule:(.*)$', s): 126 | module = m.group(1).strip() 127 | try: 128 | __import__(module) 129 | except ImportError: 130 | print(('Skipping %r (required module %r not found)' % 131 | (os.path.split(filename)[-1], module))) 132 | return False 133 | return True 134 | 135 | 136 | if __name__=='__main__': 137 | main() 138 | -------------------------------------------------------------------------------- /doc/custom.css: -------------------------------------------------------------------------------- 1 | /* 2 | :Author: Edward Loper 3 | :Copyright: This stylesheet has been placed in the public domain. 4 | 5 | Stylesheet for use with Docutils. 6 | */ 7 | 8 | @import url("docutils.css"); 9 | 10 | /*===================================================================*/ 11 | /* Navigation box */ 12 | 13 | table.navbox { 14 | border-right: 1px solid black; 15 | border-left: 1px solid black; 16 | border-bottom: 1px solid black; 17 | } 18 | td.nav { 19 | border: 2px outset #70b0ff; 20 | background: #70b0ff; color: black; 21 | font-weight: bold; 22 | } 23 | td.navselect { 24 | background: #4888d8; color: white; 25 | } 26 | 27 | a.nav:link { text-decoration: none; } 28 | a.nav:visited { text-decoration: none; } 29 | 30 | /*======================================================================*/ 31 | /* Source code colorization */ 32 | pre.py-doctest { padding: .5em; margin: 1em; 33 | background: #e8f0f8; color: #000000; 34 | border: 1px solid #708890; } 35 | table.docutils pre.py-doctest { background: #dce4ec; 36 | color: #000000; 37 | border: 1px solid #708890; } 38 | .py-prompt { color: #005050; font-weight: bold;} 39 | .py-string { color: #006030; } 40 | .py-comment { color: #003060; } 41 | .py-keyword { color: #600000; } 42 | .py-output { color: #404040; } 43 | .py-name { color: #000050; } 44 | .py-name:link { color: #000050; } 45 | .py-name:visited { color: #000050; } 46 | .py-number { color: #005000; } 47 | .py-def-name { color: #000060; font-weight: bold; } 48 | .py-base-class { color: #000060; } 49 | .py-param { color: #000060; } 50 | .py-docstring { color: #006030; } 51 | .py-decorator { color: #804020; } 52 | 53 | /*======================================================================*/ 54 | /* Document formatting */ 55 | 56 | @media screen { 57 | body { background: #204060; color: #000000; } 58 | div.document { 59 | background: white; color: black; 60 | padding: 0 1em 0 1em; 61 | border: 2px solid black; 62 | } 63 | } 64 | 65 | h1.title { font-size: 180%; font-weight: bold; text-align: center; 66 | padding: .1em; margin: 0; border-bottom: 2px solid black;} 67 | 68 | h2.subtitle { font-size: 100%; text-align: center; 69 | font-style: italic; font-weight: normal; margin-top: 0; } 70 | 71 | pre.literal-block { padding: .5em; margin: 1em; 72 | background: #e8f0f8; color: #000000; 73 | border: 1px solid #708890; } 74 | 75 | table.docutils { 76 | border: 1px solid black; background: #e8f0f8; 77 | margin-top: 6px; border-collapse: collapse; 78 | } 79 | table.docutils th, table.docutils td { 80 | border: 1px solid black; 81 | padding: 0 .5em 0 .5em; } 82 | table.docutils th { background: #70b0ff; } 83 | 84 | div.epydoc-usage { border: 1px solid #708890; 85 | background: #e8f0f8; margin: 1em; padding: 0.5em} 86 | table.option-list { background: none !important; 87 | border: 0px solid black; } 88 | table.option-list td { border: none !important; } 89 | 90 | div.note { 91 | border: 1px solid black; background: #e8f0f8; 92 | margin-top: 6px; 93 | border-collapse: collapse; 94 | padding: 0 10px 10px 10px; 95 | } 96 | div.note p.admonition-title { 97 | background: #a0f0c0; margin: 0 -10px; padding: 6px 6px 3px 6px; 98 | border-bottom: 1px solid black; 99 | } 100 | 101 | #the-epytext-markup-language table.docutils { width: 95%; } 102 | 103 | table.docutils pre { border: 0px solid black; } 104 | 105 | div.note { } 106 | 107 | 108 | 109 | /* For the "Sections" example in the manual */ 110 | p.h1 { font-size: 150%; font-weight: bold; } 111 | p.h2 { font-size: 125%; font-weight: bold; } 112 | 113 | table.docinfo { margin: 0 0 0.5em 0; font-size: 90%; } 114 | 115 | div.abstract { margin: 0; padding: 0.5em 1em; 116 | border: 1px solid black; 117 | background: #e8f0f8; color: black; } 118 | div.abstract p { margin: 0; } 119 | div.abstract p.topic-title { display: none; } 120 | 121 | #contents { 122 | background: #e8f0f8; color: black; 123 | border: 1px solid #000000; 124 | margin: 1em 0 1em 0; 125 | padding: 0 10px 0 10px; 126 | } 127 | 128 | #contents p.topic-title { 129 | background: #70b0ff; 130 | text-align: center; 131 | font-weight: bold; 132 | font-size: 125%; 133 | margin: 0 -10px 0 -10px; 134 | padding: 0 10px 0 10px; 135 | border-bottom: 1px solid black; 136 | } 137 | 138 | /* 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 |
Author:Edward Loper
Version:3.0b1
150 |
*/ 151 | -------------------------------------------------------------------------------- /doc/epydoc.css: -------------------------------------------------------------------------------- 1 | /* 2 | * Cascading Style Sheet for edloper's webpage 3 | * Copyright (C) 2002 Edward Loper 4 | * 5 | * This stylesheet is used to give my webpage a consistant feel. 6 | * My webpage currently resides at 7 | */ 8 | 9 | /*===================================================================*/ 10 | /* Default body appearance */ 11 | 12 | body { background: #b4ccd4; color: #000000; } 13 | 14 | @media print { 15 | body { font-family: times,serif; font-size: 10pt; } 16 | } 17 | 18 | @media screen { 19 | body { background: #204060; color: #000000; } 20 | div.body { 21 | background: white; color: black; 22 | /* background: #c8e0e8; color: #000000;*/ 23 | padding: 0 1em 0 1em; 24 | border: 2px solid black; 25 | /* border: 2px groove #c0d0d0;*/ 26 | } 27 | } 28 | 29 | /*===================================================================*/ 30 | /* Headlines. */ 31 | 32 | h1 { font-size: 180%; font-weight: bold; text-align: center; 33 | padding: .1em; margin: 0; border-bottom: 2px solid black;} 34 | h2 { font-size: 150%; font-weight: bold; } 35 | h3 { font-size: 140%; font-weight: bold; font-style: italic; } 36 | h4 { font-size: 130%; font-weight: bold; font-style: italic; } 37 | 38 | /*===================================================================*/ 39 | /* Font alignment. */ 40 | 41 | .left { text-align: left; } 42 | .center { text-align: center; } 43 | .right { text-align: right; } 44 | 45 | /*===================================================================*/ 46 | /* Tables */ 47 | 48 | table { background: #ffffff; color: #000000; border: 1px solid black;} 49 | th { background: #70b0ff; color: #000000; 50 | font-weight: bold; border: 1px solid black; } 51 | td { border: 1px solid black; background: #e8f0f8; color: #000000; } 52 | th.secondary { background: #ffffff; color: #000000; 53 | font-weight: bold; font-style: italic; } 54 | 55 | /* Tables used for placement */ 56 | table.transparent { background: transparent; border-width: 0; } 57 | td.transparent { background: transparent; border-width: 0; } 58 | 59 | /* Tables used for screenshots */ 60 | .screenshot { background: #c8e0e8; color: #000000; } 61 | 62 | th.index { background: red; } 63 | 64 | /*===================================================================*/ 65 | /* Lists. */ 66 | 67 | ul.nomargin { margin-top: 0; margin-bottom: 0; } 68 | 69 | /*===================================================================*/ 70 | /* Index page. */ 71 | 72 | #documentation-box table { margin-top: 0.7em; } 73 | #documentation-box ul, #documentation-box ol 74 | { margin: 0; padding: 0 0 0 2em; font-size: 90%;} 75 | #documentation-box td { padding: 0 0 1em 0; } 76 | #documentation-box p { margin: 0; padding: 0; } 77 | #feedback-box ul 78 | { margin: 0.5em 0 0.7em 2em; padding: 0; } 79 | 80 | /*===================================================================*/ 81 | /* Link colors. */ 82 | 83 | a:link { background: transparent; color: #104060; } 84 | a:visited { background: transparent; color: #082840; } 85 | 86 | /*===================================================================*/ 87 | /* Date stamp. */ 88 | 89 | .datestamp { font-size: 70%; color: #e0f0ff; } 90 | 91 | /*===================================================================*/ 92 | /* Generic box. Usually used with DIV. */ 93 | 94 | .box { 95 | background: #e8f0f8; color: black; 96 | border: 2px solid #000000; 97 | margin: 1em 0 1em 0; 98 | padding: 0 10px 0 10px; 99 | } 100 | 101 | .box-title { 102 | background: #70b0ff; 103 | text-align: center; 104 | font-weight: bold; 105 | font-size: 125%; 106 | margin: 0 -10px 0 -10px; 107 | padding: 0 10px 0 10px; 108 | border-bottom: 2px solid black; 109 | } 110 | 111 | .doclist { padding: 0; margin: 0 0 0 1em; } 112 | 113 | .caption { font-style: italic; text-align: center; } 114 | 115 | dl.faq dt { font-weight: bold; } 116 | 117 | /*===================================================================*/ 118 | /* Screen output. */ 119 | /* - prompt: a command prompt or program prompt */ 120 | /* - user: user input */ 121 | /* - (more will be added as I use them) */ 122 | 123 | .screen { 124 | background: #e8f0f8; color: black; 125 | border: 2px solid #000000; 126 | margin: 1em 0 1em 0; 127 | padding: 0 1em 0 1em; 128 | font-family: monospace; 129 | } 130 | 131 | .screen2 { 132 | background: #c8d8e0; color: black; 133 | border: 2px solid #000000; 134 | margin: 1em 0 1em 0; 135 | padding: 0 1em 0 1em; 136 | font-family: monospace; 137 | } 138 | 139 | code.prompt { font-weight: bold; } 140 | code.user { 141 | background: transparent; color: #305040; 142 | font-style: italic; font-weight: bold; 143 | } 144 | code.string { background: transparent; color: #007000; } 145 | code.keyword { background: transparent; color: #705000; } 146 | code.function { background: transparent; color: #000080; } 147 | code.output { background: transparent; color: #505060; } 148 | code.field { background: transparent; color: #007060; } 149 | code.comment { background: transparent; color: #005080; 150 | font-style: italic; } 151 | code.pycode { background: transparent; color: #305040; } 152 | 153 | b.error { background: transparent; color: #700000; } 154 | b.error i { background: transparent; color: #604000; } 155 | 156 | /*===================================================================*/ 157 | /* Navigation box */ 158 | 159 | table.navbox { 160 | border-right: 1px solid black; 161 | border-left: 1px solid black; 162 | border-bottom: 1px solid black; 163 | } 164 | td.nav { 165 | border: 2px outset #70b0ff; 166 | background: #70b0ff; color: black; 167 | font-weight: bold; 168 | } 169 | td.navselect { 170 | background: #4888d8; color: white; 171 | } 172 | 173 | a.nav:link { text-decoration: none; } 174 | a.nav:visited { text-decoration: none; } 175 | 176 | /*===================================================================*/ 177 | /* End of stylesheet */ 178 | 179 | 180 | 181 | 182 | -------------------------------------------------------------------------------- /doc/configfile.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | Epydoc: Sample Configuration File 4 | 5 | 6 | 7 | 8 | 9 |
10 |

Sample Configuration File

11 | 12 |

Configuration files, specified using the --config option, 13 | may be used to specify both the list of objects to document, and the 14 | options that should be used to document them. Configuration files are 15 | read using the standard ConfigParser 17 | module. The following example configuration file demonstrates the 18 | various options that you can set. Lines beginning with "#" or ";" are 19 | treated as comments.

20 | 21 | 
 22 | [epydoc] # Epydoc section marker (required by ConfigParser)
 23 | 
 24 | # modules
 25 | #   The list of objects to document.  Objects can be named using
 26 | #   dotted names, module filenames, or package directory names.
 27 | #   Alases for this option include "objects" and "values".
 28 | modules: sys, os.path, re
 29 | 
 30 | # output
 31 | #   The type of output that should be generated.  Should be one
 32 | #   of: html, text, latex, dvi, ps, pdf.
 33 | output: html
 34 | 
 35 | # target
 36 | #   The path to the output directory.  May be relative or absolute.
 37 | target: html/
 38 | 
 39 | # docformat
 40 | #   The default markup language for docstrings, for modules that do
 41 | #   not define __docformat__.  Defaults to epytext.
 42 | docformat: epytext
 43 | 
 44 | # css
 45 | #   The CSS stylesheet for HTML output.  Can be the name of a builtin
 46 | #   stylesheet, or the name of a file.
 47 | css: white
 48 | 
 49 | # name
 50 | #   The documented project's name.
 51 | name: Example
 52 | 
 53 | # url
 54 | #   The documented project's URL.
 55 | url: http://some.project/
 56 | 
 57 | # link
 58 | #   HTML code for the project link in the navigation bar.  If left
 59 | #   unspecified, the project link will be generated based on the
 60 | #   project's name and URL.
 61 | link: <a href="somewhere">My Cool Project</a>
 62 | 
 63 | # top
 64 | #   The "top" page for the documentation.  Can be a URL, the name
 65 | #   of a module or class, or one of the special names "trees.html",
 66 | #   "indices.html", or "help.html"
 67 | top: os.path
 68 | 
 69 | # help
 70 | #   An alternative help file.  The named file should contain the
 71 | #   body of an HTML file; navigation bars will be added to it.
 72 | help: my_helpfile.html
 73 | 
 74 | # frames
 75 | #   Whether or not to include a frames-based table of contents.
 76 | frames: yes
 77 | 
 78 | # private
 79 | #   Whether or not to inclue private variables.  (Even if included,
 80 | #   private variables will be hidden by default.)
 81 | private: yes
 82 | 
 83 | # imports
 84 | #   Whether or not to list each module's imports.
 85 | imports: no
 86 | 
 87 | # verbosity
 88 | #   An integer indicating how verbose epydoc should be.  The default
 89 | #   value is 0; negative values will supress warnings and errors;
 90 | #   positive values will give more verbose output.
 91 | verbosity: 0
 92 | 
 93 | # parse
 94 | #   Whether or not parsing should be used to examine objects.
 95 | parse: yes
 96 | 
 97 | # introspect
 98 | #   Whether or not introspection should be used to examine objects.
 99 | introspect: yes
100 | 
101 | # graph
102 | #   The list of graph types that should be automatically included
103 | #   in the output.  Graphs are generated using the Graphviz "dot"
104 | #   executable.  Graph types include: "classtree", "callgraph",
105 | #   "umlclass".  Use "all" to include all graph types
106 | graph: all
107 | 
108 | # dotpath
109 | #   The path to the Graphviz "dot" executable, used to generate
110 | #   graphs.
111 | dotpath: /usr/local/bin/dot
112 | 
113 | # sourcecode
114 | #   Whether or not to include syntax highlighted source code in
115 | #   the output (HTML only).
116 | sourcecode: yes
117 | 
118 | # pstat
119 | #   The name of one or more pstat files (generated by the profile
120 | #   or hotshot module).  These are used to generate call graphs.
121 | pstat: profile.out
122 | 
123 | # separate-classes
124 | #   Whether each class should be listed in its own section when
125 | #   generating LaTeX or PDF output.
126 | separate-classes: no
127 | 
128 |
129 |
130 | 131 | 132 | 133 | 136 | 137 | 140 | 141 | 144 | 145 | 148 | 154 | 155 |
134 | 135 | Home 138 | 139 | Installing Epydoc 142 | 143 | Using Epydoc 146 | 147 | Epytext 149 | 150 | 151 | SourceForge
156 | 157 | 158 | -------------------------------------------------------------------------------- /doc/manual-install.txt: -------------------------------------------------------------------------------- 1 | Installing Epydoc 2 | ================= 3 | 4 | .. $Id: manual-install.txt 1692 2008-01-30 17:11:29Z edloper $ 5 | 6 | Downloading Epydoc 7 | ------------------ 8 | 9 | Epydoc can be downloaded from the `SourceForge download page`_. Epydoc is 10 | available in five formats: 11 | 12 | * RPM (``.noarch.rpm``) 13 | * Windows installer (``.win32.exe``) 14 | * Source install (``.tar.gz``) 15 | * Source install (``.zip``) 16 | * Source RPM (``.src.rpm``) 17 | 18 | .. _SourceForge download page: 19 | http://sourceforge.net/project/showfiles.php?group_id=32455 20 | 21 | If you are installing on RedHat, I recommend that you use the RPM file. If you 22 | are installing on Windows, I recommended that you use the windows installer. 23 | Otherwise, you should use one of the source install files. 24 | 25 | 26 | Getting Epydoc from Subversion 27 | ------------------------------ 28 | 29 | If you wish to keep up on the latest developments, you can get the latest 30 | version of epydoc from the `subversion repository`_:: 31 | 32 | [/home/edloper]$ svn co https://epydoc.svn.sourceforge.net/svnroot/epydoc/trunk/epydoc epydoc 33 | [/home/edloper]$ ls epydoc 34 | Makefile doc man sandbox src 35 | 36 | This will create a directory named ``epydoc`` containing the latest version of 37 | epydoc. The ``epydoc`` package itself is in ``epydoc/src/epydoc`` (so adding 38 | ``epydoc/src`` to your ``PYTHONPATH`` will let you use it). You should 39 | periodically update your copy of the subversion repository, to make sure you 40 | have all the latest changes:: 41 | 42 | [/home/edloper/epydoc]$ svn up 43 | 44 | You can browse the subversion repository here__. 45 | 46 | .. _subversion repository: http://sourceforge.net/svn/?group_id=32455 47 | .. __: http://epydoc.svn.sourceforge.net/viewcvs.cgi/epydoc/trunk/epydoc/ 48 | 49 | 50 | Installing from the RPM File 51 | ---------------------------- 52 | 53 | 1. Download the RPM file to a directory of your choice. 54 | 2. Use rpm to install the new package. :: 55 | 56 | [/tmp]$ su 57 | Password: 58 | [/tmp]# rpm -i epydoc-3.0.1.noarch.rpm 59 | 60 | 3. Once epydoc is installed, you can delete the RPM file. :: 61 | 62 | [/tmp]# rm epydoc-3.0.1.rpm 63 | 64 | 65 | Installing from the Windows Installer 66 | ------------------------------------- 67 | 68 | 1. Download and run ``epydoc-3.0.1.win32.exe``. 69 | 2. Follow the on-screen instructions. Epydoc will be installed in the epydoc 70 | subdirectory of your Python installation directory (typically 71 | ``C:\Python24\``). 72 | 3. The Windows installer creates two scripts in the ``Scripts`` subdirectory of 73 | your Python installation directory: ``epydoc.pyw`` opens the graphical user 74 | interface, and ``epydoc.py`` calls the command line interface. If you'd 75 | like, you can create shortcuts from these scripts to more convenient 76 | locations (such as your desktop or start menu). 77 | 4. Once epydoc is installed, you can delete ``epydoc-3.0.1.win32.exe``. 78 | 79 | 80 | Installing from the Source Distribution (using make) 81 | ---------------------------------------------------- 82 | 83 | 1. Download an epydoc source distribution to a directory of your choice, and 84 | uncompress it. :: 85 | 86 | [/tmp]$ wget -q http://prdownloads.sourceforge.net/epydoc/epydoc-3.0.1.tar.gz 87 | [/tmp]$ gunzip epydoc-3.0.1.tar.gz 88 | [/tmp]$ tar -xvf epydoc-3.0.1.tar 89 | 90 | 2. Use ``make install`` in the ``eydoc-3.0.1/`` directory to install 91 | epydoc. :: 92 | 93 | [/tmp]$ cd epydoc-3.0.1/ 94 | [/tmp/epydoc-3.0.1]$ su 95 | Password: 96 | [/tmp/epydoc-3.0.1]# make install 97 | running install 98 | running build 99 | [...] 100 | copying build/scripts/epydoc -> /usr/bin 101 | changing mode of /usr/bin/epydoc to 100775 102 | 103 | 3. If you'd like to keep a local copy of the documentation, then use ``make 104 | installdocs``. By default, this will install the documentation to 105 | ``/usr/share/doc/`` and the man pages to ``/usr/share/man/``. If you would 106 | prefer to install documentation to different directories (such as 107 | ``/usr/lib/doc``), then edit the ``MAN`` and ``DOC`` variables at the top of 108 | ``Makefile`` before running ``make installdocs``. :: 109 | 110 | [/tmp/epydoc-3.0.1]# make installdocs 111 | 112 | 4. Once epydoc is installed, you can delete the installation directory and the 113 | source distribution file. :: 114 | 115 | [/tmp/epydoc-3.0.1]# cd .. 116 | [/tmp]# rm -r epydoc-3.0.1 117 | [/tmp]# rm epydoc-3.0.1.tar 118 | 119 | 120 | Installing from the Source Distribution (without make) 121 | ------------------------------------------------------ 122 | 123 | 1. Download an epydoc source distribution to a directory of your choice, and 124 | uncompress it. :: 125 | 126 | [/tmp]$ wget -q http://prdownloads.sourceforge.net/epydoc/epydoc-3.0.1.tar.gz 127 | [/tmp]$ gunzip epydoc-3.0.1.tar.gz 128 | [/tmp]$ tar -xvf epydoc-3.0.1.tar 129 | 130 | 2. Use the ``setup.py`` script in the ``eydoc-3.0.1/`` directory to install 131 | epydoc. :: 132 | 133 | [/tmp]$ cd epydoc-3.0.1/ 134 | [/tmp/epydoc-3.0.1]$ su 135 | Password: 136 | [/tmp/epydoc-3.0.1]# python setup.py install 137 | running install 138 | running build 139 | [...] 140 | copying build/scripts/epydoc -> /usr/bin 141 | changing mode of /usr/bin/epydoc to 100775 142 | [/tmp/epydoc-3.0.1]# cd .. 143 | [/tmp]# 144 | 145 | 3. If you'd like to keep a local copy of the documentation, then copy it to a 146 | permanant location, such as ``/usr/share/doc/``. You may also want to copy 147 | the man pages to a permanant location, such as ``/usr/share/man/``. :: 148 | 149 | [/tmp]# cp -r epydoc-3.0.1/doc/ /usr/share/doc/epydoc/ 150 | [/tmp]# cp epydoc-3.0.1/man/* /usr/share/man/ 151 | 152 | 4. Once epydoc is installed, you can delete the installation directory and the 153 | source distribution file. :: 154 | 155 | [/tmp]# rm -r epydoc-3.0.1 156 | [/tmp]# rm epydoc-3.0.1.tar 157 | 158 | 159 | Installing on Debian 160 | -------------------- 161 | 162 | Epydoc 2.1 is available as a testing debian package (``python-epydoc``). The 163 | epydoc documentation is also available as a package (``epydoc-doc``). 164 | -------------------------------------------------------------------------------- /doc/docutils.css: -------------------------------------------------------------------------------- 1 | /* 2 | :Author: David Goodger 3 | :Contact: goodger@python.org 4 | :Date: $Date: 2006-05-21 22:44:42 +0200 (Sun, 21 May 2006) $ 5 | :Revision: $Revision: 4564 $ 6 | :Copyright: This stylesheet has been placed in the public domain. 7 | 8 | Default cascading style sheet for the HTML output of Docutils. 9 | 10 | See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to 11 | customize this style sheet. 12 | */ 13 | 14 | /* used to remove borders from tables and images */ 15 | .borderless, table.borderless td, table.borderless th { 16 | border: 0 } 17 | 18 | table.borderless td, table.borderless th { 19 | /* Override padding for "table.docutils td" with "! important". 20 | The right padding separates the table cells. */ 21 | padding: 0 0.5em 0 0 ! important } 22 | 23 | .first { 24 | /* Override more specific margin styles with "! important". */ 25 | margin-top: 0 ! important } 26 | 27 | .last, .with-subtitle { 28 | margin-bottom: 0 ! important } 29 | 30 | .hidden { 31 | display: none } 32 | 33 | a.toc-backref { 34 | text-decoration: none ; 35 | color: black } 36 | 37 | blockquote.epigraph { 38 | margin: 2em 5em ; } 39 | 40 | dl.docutils dd { 41 | margin-bottom: 0.5em } 42 | 43 | dl.docutils dt { 44 | font-weight: bold } 45 | 46 | div.abstract { 47 | margin: 2em 5em } 48 | 49 | div.abstract p.topic-title { 50 | font-weight: bold ; 51 | text-align: center } 52 | 53 | div.admonition, div.attention, div.caution, div.danger, div.error, 54 | div.hint, div.important, div.note, div.tip, div.warning { 55 | margin: 2em ; 56 | border: medium outset ; 57 | padding: 1em } 58 | 59 | div.admonition p.admonition-title, div.hint p.admonition-title, 60 | div.important p.admonition-title, div.note p.admonition-title, 61 | div.tip p.admonition-title { 62 | font-weight: bold ; 63 | font-family: sans-serif } 64 | 65 | div.attention p.admonition-title, div.caution p.admonition-title, 66 | div.danger p.admonition-title, div.error p.admonition-title, 67 | div.warning p.admonition-title { 68 | color: red ; 69 | font-weight: bold ; 70 | font-family: sans-serif } 71 | 72 | /* Uncomment (and remove this text!) to get reduced vertical space in 73 | compound paragraphs. 74 | div.compound .compound-first, div.compound .compound-middle { 75 | margin-bottom: 0.5em } 76 | 77 | div.compound .compound-last, div.compound .compound-middle { 78 | margin-top: 0.5em } 79 | */ 80 | 81 | div.dedication { 82 | margin: 2em 5em ; 83 | text-align: center ; 84 | font-style: italic } 85 | 86 | div.dedication p.topic-title { 87 | font-weight: bold ; 88 | font-style: normal } 89 | 90 | div.figure { 91 | margin-left: 2em ; 92 | margin-right: 2em } 93 | 94 | div.footer, div.header { 95 | clear: both; 96 | font-size: smaller } 97 | 98 | div.line-block { 99 | display: block ; 100 | margin-top: 1em ; 101 | margin-bottom: 1em } 102 | 103 | div.line-block div.line-block { 104 | margin-top: 0 ; 105 | margin-bottom: 0 ; 106 | margin-left: 1.5em } 107 | 108 | div.sidebar { 109 | margin-left: 1em ; 110 | border: medium outset ; 111 | padding: 1em ; 112 | background-color: #ffffee ; 113 | width: 40% ; 114 | float: right ; 115 | clear: right } 116 | 117 | div.sidebar p.rubric { 118 | font-family: sans-serif ; 119 | font-size: medium } 120 | 121 | div.system-messages { 122 | margin: 5em } 123 | 124 | div.system-messages h1 { 125 | color: red } 126 | 127 | div.system-message { 128 | border: medium outset ; 129 | padding: 1em } 130 | 131 | div.system-message p.system-message-title { 132 | color: red ; 133 | font-weight: bold } 134 | 135 | div.topic { 136 | margin: 2em } 137 | 138 | h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, 139 | h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { 140 | margin-top: 0.4em } 141 | 142 | h1.title { 143 | text-align: center } 144 | 145 | h2.subtitle { 146 | text-align: center } 147 | 148 | hr.docutils { 149 | width: 75% } 150 | 151 | img.align-left { 152 | clear: left } 153 | 154 | img.align-right { 155 | clear: right } 156 | 157 | ol.simple, ul.simple { 158 | margin-bottom: 1em } 159 | 160 | ol.arabic { 161 | list-style: decimal } 162 | 163 | ol.loweralpha { 164 | list-style: lower-alpha } 165 | 166 | ol.upperalpha { 167 | list-style: upper-alpha } 168 | 169 | ol.lowerroman { 170 | list-style: lower-roman } 171 | 172 | ol.upperroman { 173 | list-style: upper-roman } 174 | 175 | p.attribution { 176 | text-align: right ; 177 | margin-left: 50% } 178 | 179 | p.caption { 180 | font-style: italic } 181 | 182 | p.credits { 183 | font-style: italic ; 184 | font-size: smaller } 185 | 186 | p.label { 187 | white-space: nowrap } 188 | 189 | p.rubric { 190 | font-weight: bold ; 191 | font-size: larger ; 192 | color: maroon ; 193 | text-align: center } 194 | 195 | p.sidebar-title { 196 | font-family: sans-serif ; 197 | font-weight: bold ; 198 | font-size: larger } 199 | 200 | p.sidebar-subtitle { 201 | font-family: sans-serif ; 202 | font-weight: bold } 203 | 204 | p.topic-title { 205 | font-weight: bold } 206 | 207 | pre.address { 208 | margin-bottom: 0 ; 209 | margin-top: 0 ; 210 | font-family: serif ; 211 | font-size: 100% } 212 | 213 | pre.literal-block, pre.doctest-block { 214 | margin-left: 2em ; 215 | margin-right: 2em } 216 | 217 | span.classifier { 218 | font-family: sans-serif ; 219 | font-style: oblique } 220 | 221 | span.classifier-delimiter { 222 | font-family: sans-serif ; 223 | font-weight: bold } 224 | 225 | span.interpreted { 226 | font-family: sans-serif } 227 | 228 | span.option { 229 | white-space: nowrap } 230 | 231 | span.pre { 232 | white-space: pre } 233 | 234 | span.problematic { 235 | color: red } 236 | 237 | span.section-subtitle { 238 | /* font-size relative to parent (h1..h6 element) */ 239 | font-size: 80% } 240 | 241 | table.citation { 242 | border-left: solid 1px gray; 243 | margin-left: 1px } 244 | 245 | table.docinfo { 246 | margin: 2em 4em } 247 | 248 | table.docutils { 249 | margin-top: 0.5em ; 250 | margin-bottom: 0.5em } 251 | 252 | table.footnote { 253 | border-left: solid 1px black; 254 | margin-left: 1px } 255 | 256 | table.docutils td, table.docutils th, 257 | table.docinfo td, table.docinfo th { 258 | padding-left: 0.5em ; 259 | padding-right: 0.5em ; 260 | vertical-align: top } 261 | 262 | table.docutils th.field-name, table.docinfo th.docinfo-name { 263 | font-weight: bold ; 264 | text-align: left ; 265 | white-space: nowrap ; 266 | padding-left: 0 } 267 | 268 | h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, 269 | h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { 270 | font-size: 100% } 271 | 272 | ul.auto-toc { 273 | list-style-type: none } 274 | -------------------------------------------------------------------------------- /src/epydoc/test/py3/restructuredtext.doctest: -------------------------------------------------------------------------------- 1 | Regression Testing for restructuredtext 2 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3 | :RequireModule: docutils 4 | 5 | >>> from epydoc.test.util import print_warnings 6 | >>> print_warnings() 7 | 8 | Summary 9 | ======= 10 | The implementation of the summaization function works as expected. 11 | 12 | >>> from epydoc.markup import restructuredtext 13 | >>> def getsummary(s): 14 | ... p = restructuredtext.parse_docstring(s, []) 15 | ... s, o = p.summary() 16 | ... s = s.to_plaintext(None).strip() 17 | ... return s, o 18 | 19 | #Let's not lose anything! 20 | 21 | >>> getsummary("Single line") 22 | ('Single line', False) 23 | 24 | >>> getsummary("Single line.") 25 | ('Single line.', False) 26 | 27 | >>> getsummary(""" 28 | ... Single line *with* period. 29 | ... """) 30 | ('Single line with period.', False) 31 | 32 | >>> getsummary(""" 33 | ... Single line `with` period. 34 | ... 35 | ... :type: Also with a tag. 36 | ... """) 37 | ('Single line with period.', False) 38 | 39 | >>> getsummary(""" 40 | ... Other lines **with** period. 41 | ... This is attached 42 | ... """) 43 | ('Other lines with period.', True) 44 | 45 | >>> getsummary(""" 46 | ... Other lines *with* period. 47 | ... 48 | ... This is detached 49 | ... 50 | ... :type: Also with a tag. 51 | ... """) 52 | ('Other lines with period.', True) 53 | 54 | >>> getsummary(""" 55 | ... Other lines without period 56 | ... This is attached 57 | ... """) 58 | ('Other lines without period\nThis is attached', False) 59 | 60 | >>> getsummary(""" 61 | ... Other lines without period 62 | ... 63 | ... This is detached 64 | ... """) 65 | ('Other lines without period...', True) 66 | 67 | >>> getsummary(""" 68 | ... Single line *without* period 69 | ... 70 | ... :type: Also with a tag. 71 | ... """) 72 | ('Single line without period', False) 73 | 74 | >>> getsummary(""" 75 | ... This is the first line. 76 | ... 77 | ... :type: Also with a tag. 78 | ... 79 | ... Other stuff after a tag. 80 | ... """) 81 | ('This is the first line.', True) 82 | 83 | Python code 84 | =========== 85 | reStructuredText markup defines a ``python`` directive to represent a block 86 | as colorized Python code. 87 | 88 | >>> err = [] 89 | >>> p = restructuredtext.parse_docstring( 90 | ... """A test module 91 | ... 92 | ... .. python:: 93 | ... 94 | ... # This is some Python code 95 | ... def foo(): 96 | ... pass 97 | ... 98 | ... class Foo: 99 | ... def __init__(self): 100 | ... pass 101 | ... """, err) 102 | >>> err 103 | [] 104 | >>> print(p.to_html(None)) 105 |

A test module

106 | 
107 | # This is some Python code
108 | def foo():
109 |     pass
110 | 
111 | class Foo:
112 |     def __init__(self):
113 |         pass
114 | 115 | 116 | Consolidated Fields 117 | =================== 118 | 119 | >>> from epydoc.test.util import runbuilder 120 | 121 | >>> runbuilder(s=b''' 122 | ... __docformat__ = 'restructuredtext' 123 | ... class Foo: 124 | ... """This is the object docstring 125 | ... 126 | ... :Parameters: 127 | ... `a` : string 128 | ... init param. 129 | ... 130 | ... :Exceptions: 131 | ... * `ValueError`: frobnication error 132 | ... init param. 133 | ... 134 | ... :IVariables: 135 | ... `a` : date 136 | ... instance var. 137 | ... """ 138 | ... def __init__(self, a): 139 | ... pass 140 | ... ''', 141 | ... build="Foo", 142 | ... attribs="variables name value exception_descrs " 143 | ... "posargs vararg kwarg type_descr arg_types arg_descrs") 144 | ClassDoc for epydoc_test.Foo [0] 145 | +- variables 146 | +- __init__ => VariableDoc for epydoc_test.Foo.__init__ [1] 147 | | +- name = '__init__' 148 | | +- type_descr = None 149 | | +- value 150 | | +- RoutineDoc for epydoc_test.Foo.__init__ [2] 151 | | +- arg_descrs = [(['a'], 'init param.')] 152 | | +- arg_types = {'a': 'string'} 153 | | +- exception_descrs = [(DottedName('ValueError'), ... 154 | | +- kwarg = None 155 | | +- posargs = ['self', 'a'] 156 | | +- vararg = None 157 | +- a => VariableDoc for epydoc_test.Foo.a [3] 158 | +- name = 'a' 159 | +- type_descr = 'date' 160 | +- value = 161 | 162 | Misc rst constructs 163 | =================== 164 | 165 | >>> runbuilder(s=b''' 166 | ... __docformat__ = 'restructuredtext' 167 | ... 168 | ... class Foo: 169 | ... """Testing defining_module 170 | ... 171 | ... :cvar `c`: class var in class docstring 172 | ... :type `c`: str 173 | ... """ 174 | ... c = 'abc' 175 | ... 176 | ... def __init__(self): 177 | ... #: A funny number 178 | ... #: 179 | ... #: :type: float 180 | ... self.x = 108.0 181 | ... 182 | ... y = property( 183 | ... fget=lambda self: 42, 184 | ... doc="""A property has no defining module 185 | ... 186 | ... :type: int 187 | ... """) 188 | ... 189 | ... def f(self): 190 | ... """A function has a defining module 191 | ... 192 | ... :rtype: int 193 | ... """ 194 | ... return 42 195 | ... ''', 196 | ... build='Foo', 197 | ... attribs="variables name value type_descr return_type descr") 198 | ClassDoc for epydoc_test.Foo [0] 199 | +- descr = 'Testing defining_module' 200 | +- variables 201 | +- __init__ => VariableDoc for epydoc_test.Foo.__init__ [1] 202 | | +- descr = None 203 | | +- name = '__init__' 204 | | +- type_descr = None 205 | | +- value 206 | | +- RoutineDoc for epydoc_test.Foo.__init__ [2] 207 | | +- descr = None 208 | | +- return_type = None 209 | +- c => VariableDoc for epydoc_test.Foo.c [3] 210 | | +- descr = 'class var in class docstring' 211 | | +- name = 'c' 212 | | +- type_descr = 'str' 213 | | +- value 214 | | +- GenericValueDoc [4] 215 | | +- descr = None 216 | +- f => VariableDoc for epydoc_test.Foo.f [5] 217 | | +- descr = None 218 | | +- name = 'f' 219 | | +- type_descr = None 220 | | +- value 221 | | +- RoutineDoc for epydoc_test.Foo.f [6] 222 | | +- descr = 'A function has a defining module' 223 | | +- return_type = 'int' 224 | +- x => VariableDoc for epydoc_test.Foo.x [7] 225 | | +- descr = 'A funny number' 226 | | +- name = 'x' 227 | | +- type_descr = 'float' 228 | | +- value = 229 | +- y => VariableDoc for epydoc_test.Foo.y [8] 230 | +- descr = None 231 | +- name = 'y' 232 | +- type_descr = None 233 | +- value 234 | +- PropertyDoc for epydoc_test.Foo.y [9] 235 | +- descr = 'A property has no defining module' 236 | +- type_descr = 'int' 237 | -------------------------------------------------------------------------------- /src/epydoc/test/py2/restructuredtext.doctest: -------------------------------------------------------------------------------- 1 | Regression Testing for restructuredtext 2 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3 | :RequireModule: docutils 4 | 5 | >>> from epydoc.test.util import print_warnings 6 | >>> print_warnings() 7 | 8 | Summary 9 | ======= 10 | The implementation of the summaization function works as expected. 11 | 12 | >>> from epydoc.markup import restructuredtext 13 | >>> def getsummary(s): 14 | ... p = restructuredtext.parse_docstring(s, []) 15 | ... s, o = p.summary() 16 | ... s = s.to_plaintext(None).strip() 17 | ... return s, o 18 | 19 | #Let's not lose anything! 20 | 21 | >>> getsummary("Single line") 22 | (u'Single line', False) 23 | 24 | >>> getsummary("Single line.") 25 | (u'Single line.', False) 26 | 27 | >>> getsummary(""" 28 | ... Single line *with* period. 29 | ... """) 30 | (u'Single line with period.', False) 31 | 32 | >>> getsummary(""" 33 | ... Single line `with` period. 34 | ... 35 | ... :type: Also with a tag. 36 | ... """) 37 | (u'Single line with period.', False) 38 | 39 | >>> getsummary(""" 40 | ... Other lines **with** period. 41 | ... This is attached 42 | ... """) 43 | (u'Other lines with period.', True) 44 | 45 | >>> getsummary(""" 46 | ... Other lines *with* period. 47 | ... 48 | ... This is detached 49 | ... 50 | ... :type: Also with a tag. 51 | ... """) 52 | (u'Other lines with period.', True) 53 | 54 | >>> getsummary(""" 55 | ... Other lines without period 56 | ... This is attached 57 | ... """) 58 | (u'Other lines without period\nThis is attached', False) 59 | 60 | >>> getsummary(""" 61 | ... Other lines without period 62 | ... 63 | ... This is detached 64 | ... """) 65 | (u'Other lines without period...', True) 66 | 67 | >>> getsummary(""" 68 | ... Single line *without* period 69 | ... 70 | ... :type: Also with a tag. 71 | ... """) 72 | (u'Single line without period', False) 73 | 74 | >>> getsummary(""" 75 | ... This is the first line. 76 | ... 77 | ... :type: Also with a tag. 78 | ... 79 | ... Other stuff after a tag. 80 | ... """) 81 | (u'This is the first line.', True) 82 | 83 | Python code 84 | =========== 85 | reStructuredText markup defines a ``python`` directive to represent a block 86 | as colorized Python code. 87 | 88 | >>> err = [] 89 | >>> p = restructuredtext.parse_docstring( 90 | ... """A test module 91 | ... 92 | ... .. python:: 93 | ... 94 | ... # This is some Python code 95 | ... def foo(): 96 | ... pass 97 | ... 98 | ... class Foo: 99 | ... def __init__(self): 100 | ... pass 101 | ... """, err) 102 | >>> err 103 | [] 104 | >>> print(p.to_html(None)) 105 |

A test module

106 | 
107 | # This is some Python code
108 | def foo():
109 |     pass
110 | 
111 | class Foo:
112 |     def __init__(self):
113 |         pass
114 | 115 | 116 | Consolidated Fields 117 | =================== 118 | 119 | >>> from epydoc.test.util import runbuilder 120 | 121 | >>> runbuilder(s=''' 122 | ... __docformat__ = 'restructuredtext' 123 | ... class Foo: 124 | ... """This is the object docstring 125 | ... 126 | ... :Parameters: 127 | ... `a` : string 128 | ... init param. 129 | ... 130 | ... :Exceptions: 131 | ... * `ValueError`: frobnication error 132 | ... init param. 133 | ... 134 | ... :IVariables: 135 | ... `a` : date 136 | ... instance var. 137 | ... """ 138 | ... def __init__(self, a): 139 | ... pass 140 | ... ''', 141 | ... build="Foo", 142 | ... attribs="variables name value exception_descrs " 143 | ... "posargs vararg kwarg type_descr arg_types arg_descrs") 144 | ClassDoc for epydoc_test.Foo [0] 145 | +- variables 146 | +- __init__ => VariableDoc for epydoc_test.Foo.__init__ [1] 147 | | +- name = '__init__' 148 | | +- type_descr = None 149 | | +- value 150 | | +- RoutineDoc for epydoc_test.Foo.__init__ [2] 151 | | +- arg_descrs = [([u'a'], u'init param.')] 152 | | +- arg_types = {u'a': u'string'} 153 | | +- exception_descrs = [(DottedName(u'ValueError'), ... 154 | | +- kwarg = None 155 | | +- posargs = ['self', 'a'] 156 | | +- vararg = None 157 | +- a => VariableDoc for epydoc_test.Foo.a [3] 158 | +- name = u'a' 159 | +- type_descr = u'date' 160 | +- value = 161 | 162 | Misc rst constructs 163 | =================== 164 | 165 | >>> runbuilder(s=''' 166 | ... __docformat__ = 'restructuredtext' 167 | ... 168 | ... class Foo: 169 | ... """Testing defining_module 170 | ... 171 | ... :cvar `c`: class var in class docstring 172 | ... :type `c`: str 173 | ... """ 174 | ... c = 'abc' 175 | ... 176 | ... def __init__(self): 177 | ... #: A funny number 178 | ... #: 179 | ... #: :type: float 180 | ... self.x = 108.0 181 | ... 182 | ... y = property( 183 | ... fget=lambda self: 42, 184 | ... doc="""A property has no defining module 185 | ... 186 | ... :type: int 187 | ... """) 188 | ... 189 | ... def f(self): 190 | ... """A function has a defining module 191 | ... 192 | ... :rtype: int 193 | ... """ 194 | ... return 42 195 | ... ''', 196 | ... build='Foo', 197 | ... attribs="variables name value type_descr return_type descr") 198 | ClassDoc for epydoc_test.Foo [0] 199 | +- descr = u'Testing defining_module' 200 | +- variables 201 | +- __init__ => VariableDoc for epydoc_test.Foo.__init__ [1] 202 | | +- descr = None 203 | | +- name = '__init__' 204 | | +- type_descr = None 205 | | +- value 206 | | +- RoutineDoc for epydoc_test.Foo.__init__ [2] 207 | | +- descr = None 208 | | +- return_type = None 209 | +- c => VariableDoc for epydoc_test.Foo.c [3] 210 | | +- descr = u'class var in class docstring' 211 | | +- name = 'c' 212 | | +- type_descr = u'str' 213 | | +- value 214 | | +- GenericValueDoc [4] 215 | | +- descr = None 216 | +- f => VariableDoc for epydoc_test.Foo.f [5] 217 | | +- descr = None 218 | | +- name = 'f' 219 | | +- type_descr = None 220 | | +- value 221 | | +- RoutineDoc for epydoc_test.Foo.f [6] 222 | | +- descr = u'A function has a defining module' 223 | | +- return_type = u'int' 224 | +- x => VariableDoc for epydoc_test.Foo.x [7] 225 | | +- descr = u'A funny number' 226 | | +- name = u'x' 227 | | +- type_descr = u'float' 228 | | +- value = 229 | +- y => VariableDoc for epydoc_test.Foo.y [8] 230 | +- descr = None 231 | +- name = 'y' 232 | +- type_descr = None 233 | +- value 234 | +- PropertyDoc for epydoc_test.Foo.y [9] 235 | +- descr = u'A property has no defining module' 236 | +- type_descr = u'int' 237 | -------------------------------------------------------------------------------- /doc/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | Epydoc 4 | 5 | 6 | 7 | 8 | 9 |
10 |

Epydoc

11 |
Automatic API Documentation Generation for Python
12 | 13 | 14 |
15 | 16 | 17 |
18 |

Overview

Epydoc is a tool for 19 | generating API documentation for Python modules, based on their 20 | docstrings. For an example of epydoc's output, see the API 21 | documentation for epydoc itself (html, pdf). A lightweight markup language called epytext can be used to format docstrings, and 24 | to add information about specific fields, such as parameters and 25 | instance variables. Epydoc also understands docstrings written in 26 | reStructuredText, 27 | Javadoc, and plaintext. For a more extensive example 28 | of epydoc's output, see the API documentation for Python 2.5.

30 |
31 | 32 | 33 |
34 |

Documentation

35 | 36 | 37 |
38 | 39 |

Epydoc manual

41 | 51 | 52 | 		53 | 54 |

Related Information

55 | 63 | 64 |
65 |

API 66 | Documentation

67 | 		68 |

Frequently Asked 69 | Questions

70 |
71 | 72 | 73 |
74 | 75 | 76 |
77 |

Feedback

78 | 86 | 87 |
88 | 89 | 90 | 		91 | 92 | 93 |
94 |

Latest Release

95 | 96 |

The latest stable release is Epydoc 3.0. If you wish to keep up on the latest developments, 99 | you can also get epydoc from the subversion repository. See Installing Epydoc for more 102 | information.

103 |
104 | 105 | 106 |
107 |

Screenshots

108 |
109 | 110 | 111 | 113 | 115 | 117 | 119 | 120 |
Generated HTML documentation for epydoc
112 | 		Example of a UML graph generated by epydoc
114 | 		Example of syntax highlighted source, w/ links to API docs
116 | 		Identifier index page for generated Python 2.4 docs
118 |
121 |
122 |
123 | 124 | 125 |
126 |

News

127 | 128 |

Epydoc 3.0 released [January 2008]
Epydoc version 3.0 is now 129 | available on the SourceForge download page. See the What's New page for details. Epydoc is under 133 | active development; if you wish to keep up on the latest developments, 134 | you can get epydoc from the subversion repository. If you 136 | find any bugs, or have suggestions for improving it, please report 137 | them on sourceforge.

138 | 139 |

Presentation at PyCon [March 2004]
Epydoc was 140 | presented at PyCon by 141 | Edward Loper. Video and audio from the 142 | presentation are available for download.

143 |
144 | 145 |
146 | 147 | 148 | 149 |
150 | 151 | 152 | 153 | 154 | 155 | 156 | 159 | 160 | 163 | 164 | 167 | 168 | 171 | 177 | 178 |
157 | 158 | Home 161 | 162 | Installing Epydoc 165 | 166 | Using Epydoc 169 | 170 | Epytext 172 | 173 | 174 | SourceForge
179 | 180 | 181 | 182 | -------------------------------------------------------------------------------- /doc/stylesheet.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | Default Epydoc CSS Stylesheet 4 | 5 | 6 | 7 | 8 | 9 |
10 |

Default Epydoc CSS Stylesheet

11 | 12 |

Note: this is not up-to-date.

13 | 14 | 
 15 | /* Body color */
 16 | body               { background: #ffffff; color: #000000; }
 17 | 
 18 | /* Tables */
 19 | table.summary, table.details, table.index
 20 |                    { background: #e8f0f8; color: #000000; }
 21 | tr.summary, tr.details, tr.index
 22 |                    { background: #70b0f0; color: #000000;
 23 |                      text-align: left; font-size: 120%; }
 24 | 
 25 | /* Headings */
 26 | h1.heading         { font-size: +140%; font-style: italic;
 27 |                      font-weight: bold; }
 28 | h2.heading         { font-size: +125%; font-style: italic;
 29 |                      font-weight: bold; }
 30 | h3.heading         { font-size: +110%; font-style: italic;
 31 |                      font-weight: normal; }
 32 | 
 33 | /* Base tree */
 34 | pre.base-tree      { font-size: 80%; }
 35 | 
 36 | /* Details Sections */
 37 | table.func-details { background: #e8f0f8; color: #000000;
 38 |                      border: 2px groove #c0d0d0;
 39 |                      padding: 0 1em 0 1em; margin: 0.4em 0 0 0; }
 40 | h3.func-detail     { background: transparent; color: #000000;
 41 |                      margin: 0 0 1em 0; }
 42 | 
 43 | table.var-details  { background: #e8f0f8; color: #000000;
 44 |                      border: 2px groove #c0d0d0;
 45 |                      padding: 0 1em 0 1em; margin: 0.4em 0 0 0; }
 46 | h3.var-details     { background: transparent; color: #000000;
 47 |                      margin: 0 0 1em 0; }
 48 | 
 49 | /* Function signatures */
 50 | .sig               { background: transparent; color: #000000;
 51 |                      font-weight: bold; }
 52 | .sig-name          { background: transparent; color: #006080; }
 53 | .sig-arg, .sig-kwarg, .sig-vararg
 54 |                    { background: transparent; color: #008060; }
 55 | .sig-default       { background: transparent; color: #602000; }
 56 | .summary-sig       { background: transparent; color: #000000; }
 57 | .summary-sig-name  { background: transparent; font-weight: bold; }
 58 | .summary-sig-arg, .summary-sig-kwarg, .summary-sig-vararg
 59 |                    { background: transparent; color: #008060; }
 60 | 
 61 | /* Doctest blocks */
 62 | .pysrc             { background: transparent; color: #000000; }
 63 | .pyprompt          { background: transparent; color: #003030;
 64 |                      font-weight: bold;}
 65 | .pystring          { background: transparent; color: #006030; }
 66 | .pycomment         { background: transparent; color: #003060; }
 67 | .pykeyword         { background: transparent; color: #402000; }
 68 | .pyoutput          { background: transparent; color: #404040; }
 69 | 
 70 | /* Navigation bar */
 71 | table.navbar       { background: #a0c0ff; color: #000000;
 72 |                      border: 2px groove #c0d0d0; }
 73 | th.navbar          { background: #a0c0ff; color: #6090d0; font-size: 110% }
 74 | th.navselect       { background: #70b0ff; color: #000000; font-size: 110% }
 75 | 
 76 | /* Links */
 77 | a:link             { background: transparent; color: #0000ff; }
 78 | a:visited          { background: transparent; color: #204080; }
 79 | a.navbar:link      { background: transparent; color: #0000ff;
 80 |                      text-decoration: none; }
 81 | a.navbar:visited   { background: transparent; color: #204080;
 82 |                      text-decoration: none; }
 83 |
84 | 85 |
86 | 87 | 88 | 89 | 92 | 93 | 96 | 97 | 100 | 101 | 104 | 110 | 111 |
90 | 91 | Home 94 | 95 | Installing Epydoc 98 | 99 | Using Epydoc 102 | 103 | Epytext 105 | 106 | 107 | SourceForge
112 | 113 | 114 | -------------------------------------------------------------------------------- /src/epydoc/log.py: -------------------------------------------------------------------------------- 1 | # epydoc -- Logging 2 | # 3 | # Copyright (C) 2005 Edward Loper 4 | # Author: Edward Loper 5 | # URL: 6 | # 7 | # $Id: log.py 1704 2008-02-01 19:15:34Z edloper $ 8 | 9 | """ 10 | Functions used to report messages and progress updates to the user. 11 | These functions are delegated to zero or more registered L{Logger} 12 | objects, which are responsible for actually presenting the information 13 | to the user. Different interfaces are free to create and register 14 | their own C{Logger}s, allowing them to present this information in the 15 | manner that is best suited to each interface. 16 | 17 | @note: I considered using the standard C{logging} package to provide 18 | this functionality. However, I found that it would be too difficult 19 | to get that package to provide the behavior I want (esp. with respect 20 | to progress displays; but also with respect to message blocks). 21 | 22 | @group Message Severity Levels: DEBUG, INFO, WARNING, ERROR, FATAL 23 | """ 24 | 25 | from __future__ import absolute_import 26 | from __future__ import print_function 27 | 28 | __docformat__ = 'epytext en' 29 | 30 | import sys, os 31 | 32 | DEBUG = 10 33 | INFO = 20 34 | DOCSTRING_WARNING = 25 35 | WARNING = 30 36 | ERROR = 40 37 | FATAL = 40 38 | 39 | ###################################################################### 40 | # Logger Base Class 41 | ###################################################################### 42 | class Logger: 43 | """ 44 | An abstract base class that defines the interface for X{loggers}, 45 | which are used by epydoc to report information back to the user. 46 | Loggers are responsible for tracking two types of information: 47 | 48 | - Messages, such as warnings and errors. 49 | - Progress on the current task. 50 | 51 | This abstract class allows the command-line interface and the 52 | graphical interface to each present this information to the user 53 | in the way that's most natural for each interface. To set up a 54 | logger, create a subclass of C{Logger} that overrides all methods, 55 | and register it using L{register_logger}. 56 | """ 57 | #//////////////////////////////////////////////////////////// 58 | # Messages 59 | #//////////////////////////////////////////////////////////// 60 | 61 | def log(self, level, message): 62 | """ 63 | Display a message. 64 | 65 | @param message: The message string to display. C{message} may 66 | contain newlines, but does not need to end in a newline. 67 | @param level: An integer value indicating the severity of the 68 | message. 69 | """ 70 | 71 | def close(self): 72 | """ 73 | Perform any tasks needed to close this logger. This should 74 | be safe to call multiple times. 75 | """ 76 | 77 | #//////////////////////////////////////////////////////////// 78 | # Message blocks 79 | #//////////////////////////////////////////////////////////// 80 | 81 | def start_block(self, header): 82 | """ 83 | Start a new message block. Any calls to L{info()}, 84 | L{warning()}, or L{error()} that occur between a call to 85 | C{start_block} and a corresponding call to C{end_block} will 86 | be grouped together, and displayed with a common header. 87 | C{start_block} can be called multiple times (to form nested 88 | blocks), but every call to C{start_block} I{must} be balanced 89 | by a call to C{end_block}. 90 | """ 91 | 92 | def end_block(self): 93 | """ 94 | End a warning block. See L{start_block} for details. 95 | """ 96 | 97 | #//////////////////////////////////////////////////////////// 98 | # Progress bar 99 | #//////////////////////////////////////////////////////////// 100 | 101 | def start_progress(self, header=None): 102 | """ 103 | Begin displaying progress for a new task. C{header} is a 104 | description of the task for which progress is being reported. 105 | Each call to C{start_progress} must be followed by a call to 106 | C{end_progress} (with no intervening calls to 107 | C{start_progress}). 108 | """ 109 | 110 | def end_progress(self): 111 | """ 112 | Finish off the display of progress for the current task. See 113 | L{start_progress} for more information. 114 | """ 115 | 116 | def progress(self, percent, message=''): 117 | """ 118 | Update the progress display. 119 | 120 | @param percent: A float from 0.0 to 1.0, indicating how much 121 | progress has been made. 122 | @param message: A message indicating the most recent action 123 | that contributed towards that progress. 124 | """ 125 | 126 | class SimpleLogger(Logger): 127 | def __init__(self, threshold=WARNING): 128 | self.threshold = threshold 129 | def log(self, level, message): 130 | if level >= self.threshold: print(message) 131 | 132 | ###################################################################### 133 | # Logger Registry 134 | ###################################################################### 135 | 136 | _loggers = [] 137 | """ 138 | The list of registered logging functions. 139 | """ 140 | 141 | def register_logger(logger): 142 | """ 143 | Register a logger. Each call to one of the logging functions 144 | defined by this module will be delegated to each registered 145 | logger. 146 | """ 147 | _loggers.append(logger) 148 | 149 | def remove_logger(logger, close_logger=True): 150 | if close_logger: logger.close() 151 | _loggers.remove(logger) 152 | 153 | ###################################################################### 154 | # Logging Functions 155 | ###################################################################### 156 | # The following methods all just delegate to the corresponding 157 | # methods in the Logger class (above) for each registered logger. 158 | 159 | def fatal(*messages): 160 | """Display the given fatal message.""" 161 | message = ' '.join(['%s' % (m,) for m in messages]) 162 | for logger in _loggers: logger.log(FATAL, message) 163 | 164 | def error(*messages): 165 | """Display the given error message.""" 166 | message = ' '.join(['%s' % (m,) for m in messages]) 167 | for logger in _loggers: logger.log(ERROR, message) 168 | 169 | def warning(*messages): 170 | """Display the given warning message.""" 171 | message = ' '.join(['%s' % (m,) for m in messages]) 172 | for logger in _loggers: logger.log(WARNING, message) 173 | 174 | def docstring_warning(*messages): 175 | """Display the given docstring warning message.""" 176 | message = ' '.join(['%s' % (m,) for m in messages]) 177 | for logger in _loggers: logger.log(DOCSTRING_WARNING, message) 178 | 179 | def info(*messages): 180 | """Display the given informational message.""" 181 | message = ' '.join(['%s' % (m,) for m in messages]) 182 | for logger in _loggers: logger.log(INFO, message) 183 | 184 | def debug(*messages): 185 | """Display the given debugging message.""" 186 | message = ' '.join(['%s' % (m,) for m in messages]) 187 | for logger in _loggers: logger.log(DEBUG, message) 188 | 189 | def start_block(header): 190 | for logger in _loggers: logger.start_block(header) 191 | start_block.__doc__ = Logger.start_block.__doc__ 192 | 193 | def end_block(): 194 | for logger in _loggers: logger.end_block() 195 | end_block.__doc__ = Logger.end_block.__doc__ 196 | 197 | def start_progress(header=None): 198 | for logger in _loggers: logger.start_progress(header) 199 | start_progress.__doc__ = Logger.start_progress.__doc__ 200 | 201 | def end_progress(): 202 | for logger in _loggers: logger.end_progress() 203 | end_progress.__doc__ = Logger.end_progress.__doc__ 204 | 205 | def progress(percent, message=''): 206 | for logger in _loggers: logger.progress(percent, '%s' % message) 207 | progress.__doc__ = Logger.progress.__doc__ 208 | 209 | def close(): 210 | for logger in _loggers: logger.close() 211 | -------------------------------------------------------------------------------- /src/epydoc/docwriter/html_help.py: -------------------------------------------------------------------------------- 1 | # 2 | # epydoc.css: default help page 3 | # Edward Loper 4 | # 5 | # Created [01/30/01 05:18 PM] 6 | # $Id: html_help.py 1239 2006-07-05 11:29:50Z edloper $ 7 | # 8 | 9 | """ 10 | Default help file for the HTML outputter (L{epydoc.docwriter.html}). 11 | 12 | @type HTML_HELP: C{string} 13 | @var HTML_HELP: The contents of the HTML body for the default 14 | help page. 15 | """ 16 | __docformat__ = 'epytext en' 17 | 18 | # Expects: {'this_project': name} 19 | HTML_HELP = ''' 20 |

API Documentation

21 | 22 |

This document contains the API (Application Programming Interface) 23 | documentation for %(this_project)s. Documentation for the Python 24 | objects defined by the project is divided into separate pages for each 25 | package, module, and class. The API documentation also includes two 26 | pages containing information about the project as a whole: a trees 27 | page, and an index page.

28 | 29 |

Object Documentation

30 | 31 |

Each Package Documentation page contains:

32 |
    33 |
  • A description of the package.
    • 34 |
  • A list of the modules and sub-packages contained by the 35 | package.
    • 36 |
  • A summary of the classes defined by the package.
    • 37 |
  • A summary of the functions defined by the package.
    • 38 |
  • A summary of the variables defined by the package.
    • 39 |
  • A detailed description of each function defined by the 40 | package.
    • 41 |
  • A detailed description of each variable defined by the 42 | package.
    • 43 |
44 | 45 |

Each Module Documentation page contains:

46 |
    47 |
  • A description of the module.
    • 48 |
  • A summary of the classes defined by the module.
    • 49 |
  • A summary of the functions defined by the module.
    • 50 |
  • A summary of the variables defined by the module.
    • 51 |
  • A detailed description of each function defined by the 52 | module.
    • 53 |
  • A detailed description of each variable defined by the 54 | module.
    • 55 |
56 | 57 |

Each Class Documentation page contains:

58 |
    59 |
  • A class inheritance diagram.
    • 60 |
  • A list of known subclasses.
    • 61 |
  • A description of the class.
    • 62 |
  • A summary of the methods defined by the class.
    • 63 |
  • A summary of the instance variables defined by the class.
    • 64 |
  • A summary of the class (static) variables defined by the 65 | class.
    • 66 |
  • A detailed description of each method defined by the 67 | class.
    • 68 |
  • A detailed description of each instance variable defined by the 69 | class.
    • 70 |
  • A detailed description of each class (static) variable defined 71 | by the class.
    • 72 |
73 | 74 |

Project Documentation

75 | 76 |

The Trees page contains the module and class hierarchies:

77 |
    78 |
  • The module hierarchy lists every package and module, with 79 | modules grouped into packages. At the top level, and within each 80 | package, modules and sub-packages are listed alphabetically.
    • 81 |
  • The class hierarchy lists every class, grouped by base 82 | class. If a class has more than one base class, then it will be 83 | listed under each base class. At the top level, and under each base 84 | class, classes are listed alphabetically.
    • 85 |
86 | 87 |

The Index page contains indices of terms and 88 | identifiers:

89 |
    90 |
  • The term index lists every term indexed by any object\'s 91 | documentation. For each term, the index provides links to each 92 | place where the term is indexed.
    • 93 |
  • The identifier index lists the (short) name of every package, 94 | module, class, method, function, variable, and parameter. For each 95 | identifier, the index provides a short description, and a link to 96 | its documentation.
    • 97 |
98 | 99 |

The Table of Contents

100 | 101 |

The table of contents occupies the two frames on the left side of 102 | the window. The upper-left frame displays the project 103 | contents, and the lower-left frame displays the module 104 | contents:

105 | 106 | 107 | 108 | 110 | 113 | 114 | 115 | 118 | 119 |
109 | Project
Contents
...		 111 | API
Documentation
Frame


112 |
116 | Module
Contents
 
...
  117 |

120 | 121 |

The project contents frame contains a list of all packages 122 | and modules that are defined by the project. Clicking on an entry 123 | will display its contents in the module contents frame. Clicking on a 124 | special entry, labeled "Everything," will display the contents of 125 | the entire project.

126 | 127 |

The module contents frame contains a list of every 128 | submodule, class, type, exception, function, and variable defined by a 129 | module or package. Clicking on an entry will display its 130 | documentation in the API documentation frame. Clicking on the name of 131 | the module, at the top of the frame, will display the documentation 132 | for the module itself.

133 | 134 |

The "frames" and "no frames" buttons below the top 135 | navigation bar can be used to control whether the table of contents is 136 | displayed or not.

137 | 138 |

The Navigation Bar

139 | 140 |

A navigation bar is located at the top and bottom of every page. 141 | It indicates what type of page you are currently viewing, and allows 142 | you to go to related pages. The following table describes the labels 143 | on the navigation bar. Note that not some labels (such as 144 | [Parent]) are not displayed on all pages.

145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 | 159 | 160 | 161 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | 172 | 173 | 174 | 175 |
LabelHighlighted when...Links to...
[Parent](never highlighted) the parent of the current package
[Package]viewing a packagethe package containing the current object 158 |
[Module]viewing a modulethe module containing the current object 162 |
[Class]viewing a class the class containing the current object
[Trees]viewing the trees page the trees page
[Index]viewing the index page the index page
[Help]viewing the help page the help page
176 | 177 |

The "show private" and "hide private" buttons below 178 | the top navigation bar can be used to control whether documentation 179 | for private objects is displayed. Private objects are usually defined 180 | as objects whose (short) names begin with a single underscore, but do 181 | not end with an underscore. For example, "_x", 182 | "__pprint", and "epydoc.epytext._tokenize" 183 | are private objects; but "re.sub", 184 | "__init__", and "type_" are not. However, 185 | if a module defines the "__all__" variable, then its 186 | contents are used to decide which objects are private.

187 | 188 |

A timestamp below the bottom navigation bar indicates when each 189 | page was last updated.

190 | ''' 191 | -------------------------------------------------------------------------------- /doc/othermarkup.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | Alternate Markup Languages 4 | 5 | 6 | 7 | 8 |
9 |

Alternate Markup Languages

10 | 11 |

Epydoc's default markup language is epytext, a lightweight markup language that's 13 | easy to write and to understand. But if epytext is not powerful enough 14 | for you, or doesn't suit your needs, epydoc also supports three 15 | alternate markup languages:

16 | 17 |
    18 |
  • reStructuredText is an "easy-to-read, 20 | what-you-see-is-what-you-get plaintext markup syntax." It is more 21 | powerful than epytext (e.g., it includes markup for tables and 22 | footnotes); but it is also more complex, and sometimes harder to 23 | read.
    • 24 | 25 |
  • Javadoc is a documentation markup language that was 27 | developed for Java. It consists of HTML, augmented by a set of 28 | special tagged fields.
    • 29 | 30 |
  • Plaintext docstrings are rendered verbatim (preserving 31 | whitespace).
    • 32 |
33 | 34 |

To specify the markup language for a module, you should define a 35 | module-level string variable __docformat__, containing 36 | the name of the module's markup language. The name of the markup 37 | language may optionally be followed by a language code (such as 38 | en for English). Conventionally, the definition of the 39 | __docformat__ variable immediately follows the module's 40 | docstring:

41 | 42 |
43 | 
 44 | # widget.py
 45 | """
 46 | Graphical support for `gizmos` and `widgets`.
 47 | """
 48 | __docformat__ = "restructuredtext en"
 49 | [...]
 50 |
51 | 52 |

To change the default markup language from the command line, use 53 | the --docformat option. For example, the following 54 | command generates API documentation for the existing regular 55 | expression package re, which uses plaintext markup:

56 | 57 | 
 58 | [epydoc]$ epydoc --docformat plaintext re
 59 |
60 | 61 | 62 |

reStructuredText

 63 | 64 |

reStructuredText is a markup language that was developed in 65 | conjunction with Docutils. In order to 67 | parse reStructuredText docstrings, Docutils 0.3 or higher must be 68 | installed. If Docutils is not installed, then reStructuredText 69 | docstrings will be rendered as plaintext. Docutils can be downloaded 70 | from the Docutils 72 | SourceForge page.

73 | 74 |

In addition to the standard set of 75 | fields, the reStructruedText parser also supports 76 | consolidated fields, which combine the documentation for 77 | several objects into a single field. For more information, see the 78 | markup-specific notes for reStructuredText 79 | fields.

80 | 81 |

The epydoc reStructuredText reader also defines several custom directives, 83 | which can be used to automatically generate a variety of graphs. The 84 | following custom directives are currently defined:

85 | 86 | 87 | 88 | 89 | 93 | 100 | 101 | 106 | 115 | 116 | 120 | 127 | 128 | 132 | 139 | 140 | 145 | 155 | 156 | 157 |
DirectiveDescription
 90 | .. classtree:: [classes...]
 91 |     :dir: up|down|left|right
 92 |
94 | Display a class hierarchy for the given class or classes (including 95 | all superclasses & subclasses). If no class is specified, and the 96 | directive is used in a class's docstring, then that class's class 97 | hierarchy will be displayed. The dir option specifies 98 | the orientation for the graph (default=down). 99 | 
102 | .. packagetree:: [modules...]
103 |     :dir: up|down|left|right
104 |     :style: uml|tree
105 |
107 | Display a package hierarchy for the given module or modules (including 108 | all subpackages and submodules). If no module is specified, and the 109 | directive is used in a module's docstring, then that module's package 110 | hierarchy will be displayed. The dir option specifies 111 | the orientation for the graph (default=down). The 112 | style option specifies whether packages should be 113 | displayed in a tree, or using nested UML symbols. 114 | 
117 | .. importgraph:: [modules...]
118 |     :dir: up|down|left|right
119 |
121 | Display an import graph for the given module or modules. If no module 122 | is specified, and the directive is used in a module's docstring, then 123 | that module's import graph will be displayed. The dir 124 | option specifies the orientation for the graph 125 | (default=left). 126 | 
129 | .. callgraph:: [functions...]
130 |     :dir: up|down|left|right
131 |
133 | Display a call graph for the given function or functions. If no function 134 | is specified, and the directive is used in a function's docstring, then 135 | that function's call graph will be displayed. The 136 | dir option specifies the orientation for the graph 137 | (default=right). 138 | 
141 | .. dotgraph:: [title...]
142 |     :caption: text...
143 |     graph...
144 |
146 | 147 | Display a custom Graphviz dot graph. The body of the directive 148 | (graph...) should contain the body of a dot graph. The 149 | optional title argument, if specified, is used as the 150 | title of the graph. The optional caption option can be 151 | used to provide a caption for the graph. 152 | 153 | 154 |
158 | 159 | 160 | 161 | 162 |

Javadoc

163 | 164 |

Javadoc is a markup language developed by Sun Microsystems 166 | for documenting Java APIs. The epydoc implementation of Javadoc is 167 | based on the Javadoc 169 | 1.4.2 reference documentation. However, there are likely to be 170 | some minor incompatibilities between Sun's implementation and 171 | epydoc's. Known incompatibilities include:

172 | 173 |
    174 |
  • Epydoc does not support the Javadoc block tag 175 | @serial.
    • 176 | 177 |
  • Epydoc does not support the following Javadoc inline tags: 178 | {@docroot}, {@inheritdoc}, 179 | {@value}. 180 | 181 |
  • Epydoc adds many field tags that Sun does not include, such as 182 | @var, @type, and 183 | @group.
    • 184 |
185 | 186 |
187 | 188 | 189 | 190 | 193 | 194 | 197 | 198 | 201 | 202 | 205 | 211 | 212 |
191 | 192 | Home 195 | 196 | Installing Epydoc 199 | 200 | Using Epydoc 203 | 204 | Epytext 206 | 207 | 208 | SourceForge
213 | 214 | 215 | -------------------------------------------------------------------------------- /src/epydoc/test/apidoc.doctest: -------------------------------------------------------------------------------- 1 | Regression Testing for epydoc.apidoc 2 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3 | This file serves to provide both documentation and regression tests 4 | for the epydoc.apidoc module. The main purpose of this module is to 5 | define the `APIDoc` class hierarchy, which is used to encode API 6 | documentation about Python programs. The API documentation for a 7 | Python program is encoded using a graph of `APIDoc` objects, each of 8 | which encodes information about a single Python variable or value. 9 | 10 | >>> import epydoc; epydoc.DEBUG = True 11 | 12 | >>> from epydoc.apidoc import * 13 | 14 | >>> from epydoc.test.util import print_warnings 15 | >>> print_warnings() 16 | 17 | Unknown Value 18 | ============= 19 | Epydoc defines a special object, epydoc.apidoc.UNKNOWN, which is used 20 | as the value of attributes when their real value is not (yet) known. 21 | 22 | >>> UNKNOWN 23 | 24 | 25 | This object only compares equal to itself: 26 | 27 | >>> UNKNOWN == False 28 | False 29 | >>> UNKNOWN == True 30 | False 31 | >>> UNKNOWN == 'UNKNOWN' 32 | False 33 | >>> UNKNOWN == 0 34 | False 35 | >>> UNKNOWN == [] 36 | False 37 | >>> UNKNOWN == object() 38 | False 39 | >>> UNKNOWN == UNKNOWN 40 | True 41 | 42 | If UNKNOWN is used in a context where it is cast to bool, then it will 43 | raise an exception. This helps prevent acidentally interpreting an 44 | UNKNOWN value as true or false: 45 | 46 | >>> if UNKNOWN: 47 | ... print('ok') 48 | Traceback (most recent call last): 49 | ValueError: Sentinel value can not be used as a boolean 50 | 51 | To test an attribute whose value might be UNKNOWN, you should 52 | explicitly compare that value to True or False. E.g.: 53 | 54 | >>> x = UNKNOWN 55 | >>> if x is True: 56 | ... print('we know x is true, and not unknown') 57 | >>> if x is not False: 58 | ... print('x might be true or unknown.') 59 | x might be true or unknown. 60 | >>> if x in (True, UNKNOWN): 61 | ... print('x might be true or unknown.') 62 | x might be true or unknown. 63 | 64 | Dotted Names 65 | ============ 66 | The DottedName class is used to encode dotted names, such as 67 | 'epydoc.apidoc.DottedName', and make them easier to work with. 68 | Conceptually, a dotted name consists of a sequence of identifiers, 69 | separated by periods. 70 | 71 | Dotted names can be constructed from strings: 72 | 73 | >>> name1 = DottedName('foo.bar') 74 | >>> name1 75 | DottedName('foo', 'bar') 76 | 77 | Note that the given name is split on periods. You may also pass 78 | multiple strings to the constructor; they will be combined together 79 | into a single sequence: 80 | 81 | >>> name2 = DottedName('x.y', 'z') 82 | >>> name2 83 | DottedName('x', 'y', 'z') 84 | 85 | Each string can be a single identifier or a sequence of identifiers 86 | joined py periods. You may also pass DottedName objects to the 87 | constructor; their sequence of identifiers will be used: 88 | 89 | >>> name3 = DottedName(name1, name2) 90 | >>> name3 91 | DottedName('foo', 'bar', 'x', 'y', 'z') 92 | 93 | The string representation of a dotted name is formed by joining the 94 | identifiers with periods: 95 | 96 | >>> str(name1) 97 | 'foo.bar' 98 | >>> str(name2) 99 | 'x.y.z' 100 | >>> str(name3) 101 | 'foo.bar.x.y.z' 102 | 103 | The individual identifiers of a dotted name can be accessed via 104 | indexing; and the number of identifiers is returned by the len 105 | operator: 106 | 107 | >>> name1[0], name1[1] 108 | ('foo', 'bar') 109 | >>> name3[-1] 110 | 'z' 111 | >>> name3[1:3] 112 | DottedName('bar', 'x') 113 | >>> len(name2) 114 | 3 115 | 116 | As a result, you can iterate over the identifiers in a dotted name: 117 | 118 | >>> for ident in name1: 119 | ... print(ident) 120 | foo 121 | bar 122 | 123 | Two dotted names compare equal if they have the same number of 124 | identifies and they are pairwise equal: 125 | 126 | >>> DottedName('foo.bar') == DottedName('foo', 'bar') 127 | True 128 | >>> DottedName('foo.bar') == DottedName('foo.baz') 129 | False 130 | >>> DottedName('foo.bar') == DottedName('foo.bar.baz') 131 | False 132 | 133 | Dotted names may be combined with the addition operator: 134 | 135 | >>> name1 + name2 136 | DottedName('foo', 'bar', 'x', 'y', 'z') 137 | >>> name1 + name2 == name3 138 | True 139 | >>> name2 + name1 == name3 140 | False 141 | 142 | The container method may be used to construct a new dotted name with the 143 | last identifier stripped off: 144 | 145 | >>> name1.container() 146 | DottedName('foo') 147 | >>> name3.container() 148 | DottedName('foo', 'bar', 'x', 'y') 149 | 150 | If a dotted name has only one identifier, then its container is None: 151 | 152 | >>> print(DottedName('baz').container()) 153 | None 154 | >>> print(name1.container().container()) 155 | None 156 | 157 | It is an error to create an empty dotted name; or a dotted name that 158 | contains a string that's not a valid python identifier: 159 | 160 | >>> DottedName() # doctest: +PYMAX2.7 161 | Traceback (most recent call last): 162 | InvalidDottedName: Empty DottedName 163 | >>> DottedName() # doctest: +PYMIN3.0 164 | Traceback (most recent call last): 165 | epydoc.apidoc.DottedName.InvalidDottedName: Empty DottedName 166 | 167 | >>> DottedName('1+2', strict=True) # doctest: +PYMAX2.7 168 | Traceback (most recent call last): 169 | InvalidDottedName: Bad identifier '1+2' 170 | 171 | >>> DottedName('1+2', strict=True) # doctest: +PYMIN3.0 172 | Traceback (most recent call last): 173 | epydoc.apidoc.DottedName.InvalidDottedName: Bad identifier '1+2' 174 | 175 | >>> DottedName({}) 176 | Traceback (most recent call last): 177 | TypeError: Bad identifier {}: expected DottedName or str 178 | 179 | >>> DottedName('1+2', strict=False) 180 | Identifier '1+2' looks suspicious; using it anyway. 181 | DottedName('1+2') 182 | 183 | The one exception is that '??' is treated as if it were a valid python 184 | identifier: 185 | 186 | >>> DottedName('??', 'foo') 187 | DottedName('??', 'foo') 188 | 189 | This is used when we can't find any name for an object (e.g., if 190 | there's a class that was used as the base class, but is not contained 191 | in any module or class). 192 | 193 | A dotted name can be queried into a context to obtain a reduced version: 194 | 195 | >>> DottedName('foo.bar').contextualize(DottedName('foo')) 196 | DottedName('bar') 197 | >>> DottedName('foo.bar.baz.qux').contextualize(DottedName('foo.bar')) 198 | DottedName('baz', 'qux') 199 | >>> DottedName('foo.bar').contextualize(DottedName('baz')) 200 | DottedName('foo', 'bar') 201 | >>> DottedName('foo.bar').contextualize(DottedName('foo').container()) 202 | DottedName('foo', 'bar') 203 | >>> DottedName('foo.bar').contextualize(UNKNOWN) 204 | DottedName('foo', 'bar') 205 | 206 | But a contextualization can't reduce to an empty DottedName: 207 | 208 | >>> DottedName('foo').contextualize(DottedName('foo')) 209 | DottedName('foo') 210 | 211 | APIDoc Objects 212 | ============== 213 | API documentation about Python programs is broken into small pieces, 214 | each of which is encoded using a single APIDoc object. Each APIDoc 215 | object describes a single value, variable, or function argument. 216 | 217 | The APIDoc base class has 2 direct subclasses, for the 2 basic types 218 | of entity that it can record information about: ValueDoc and 219 | VariableDoc. ValueDoc is further subclassed to specify the different 220 | pieces of information that should be recorded about each value type. 221 | 222 | APIDoc objects record information about each entity using attributes. 223 | Attribute values may be specified in the constructor. Any attributes 224 | that are not specified will be given a default value (usually 225 | UNKNOWN). The APIDoc base class defines the attributes shared by all 226 | APIDoc objects: docstring, docstring_lineno, descr, summary, metadata, 227 | and extra_docstring_fields. 228 | 229 | >>> api_doc = APIDoc(docstring='foo') 230 | >>> api_doc.docstring 231 | 'foo' 232 | >>> api_doc.summary 233 | 234 | 235 | The constructor does not accept positional arguments; and any keyword 236 | argument that does not correspond to a valid attribute will generate a 237 | TypeError (but only if epydoc.DEBUG is true): 238 | 239 | >>> APIDoc('foo') # doctest: +PYMAX2.7 240 | Traceback (most recent call last): 241 | TypeError: __init__() takes exactly 1 argument (2 given) 242 | 243 | >>> APIDoc('foo') # doctest: +PYMIN3.0 244 | Traceback (most recent call last): 245 | TypeError: __init__() takes 1 positional argument but 2 were given 246 | 247 | >>> APIDoc(foo='foo') 248 | Traceback (most recent call last): 249 | TypeError: APIDoc got unexpected arg 'foo' 250 | 251 | Any assignment to an attribute that's not valid will also generate a 252 | TypeError (but only if epydoc.DEBUG is true): 253 | 254 | >>> api_doc = APIDoc(docstring='ds') 255 | >>> api_doc.foo = 0 256 | Traceback (most recent call last): 257 | AttributeError: APIDoc does not define attribute 'foo' 258 | 259 | APIDoc defines a pretty-print method, pp(), which can be used to 260 | display the information that an APIDoc contains: 261 | 262 | >>> val_doc = ValueDoc(pyval=3) 263 | >>> var_doc = VariableDoc(name='x', value=val_doc) 264 | >>> class_doc = ClassDoc(bases=(), variables={'x':var_doc}) 265 | >>> print(class_doc.pp()) 266 | ClassDoc [0] 267 | +- bases = () 268 | +- variables 269 | +- x => VariableDoc for x [1] 270 | +- is_public = True 271 | +- name = 'x' 272 | +- value 273 | +- ValueDoc [2] 274 | +- pyval = 3 275 | 276 | This is mainly intended to be used as a debugging and testing tool. 277 | The attributes that will be pretty-printed for an APIDoc object are 278 | determined by its class's _STR_FIELDS variable. (But any attribute 279 | whose value is UNKNOWN will not be displayed.) Attributes are listed 280 | in alphabetical order. 281 | 282 | -------------------------------------------------------------------------------- /src/epydoc/__init__.py: -------------------------------------------------------------------------------- 1 | # epydoc 2 | # 3 | # Copyright (C) 2005 Edward Loper 4 | # Author: Edward Loper 5 | # URL: 6 | # 7 | # $Id: __init__.py 1750 2008-02-23 16:09:47Z edloper $ 8 | 9 | """ 10 | Automatic Python reference documentation generator. Epydoc processes 11 | Python modules and docstrings to generate formatted API documentation, 12 | in the form of HTML pages. Epydoc can be used via a command-line 13 | interface (`epydoc.cli`) and a graphical interface (`epydoc.gui`). 14 | Both interfaces let the user specify a set of modules or other objects 15 | to document, and produce API documentation using the following steps: 16 | 17 | 1. Extract basic information about the specified objects, and objects 18 | that are related to them (such as the values defined by a module). 19 | This can be done via introspection, parsing, or both: 20 | 21 | * *Introspection* imports the objects, and examines them directly 22 | using Python's introspection mechanisms. 23 | 24 | * *Parsing* reads the Python source files that define the objects, 25 | and extracts information from those files. 26 | 27 | 2. Combine and process that information. 28 | 29 | * **Merging**: Merge the information obtained from introspection & 30 | parsing each object into a single structure. 31 | 32 | * **Linking**: Replace any \"pointers\" that were created for 33 | imported variables with the documentation that they point to. 34 | 35 | * **Naming**: Assign unique *canonical names* to each of the 36 | specified objects, and any related objects. 37 | 38 | * **Docstrings**: Parse the docstrings of each of the specified 39 | objects. 40 | 41 | * **Inheritance**: Add variables to classes for any values that 42 | they inherit from their base classes. 43 | 44 | 3. Generate output. Output can be generated in a variety of formats: 45 | 46 | * An HTML webpage. 47 | 48 | * A LaTeX document (which can be rendered as a PDF file) 49 | 50 | * A plaintext description. 51 | 52 | .. digraph:: Overview of epydoc's architecture 53 | :caption: The boxes represent steps in epydoc's processing chain. 54 | Arrows are annotated with the data classes used to 55 | communicate between steps. The lines along the right 56 | side mark what portions of the processing chain are 57 | initiated by build_doc_index() and cli(). Click on 58 | any item to see its documentation. 59 | 60 | /* 61 | Python module or value * * 62 | / \ | | 63 | V V | | 64 | introspect_docs() parse_docs() | | 65 | \ / | | 66 | V V | | 67 | merge_docs() | | 68 | | build_doc_index() cli() 69 | V | | 70 | link_imports() | | 71 | | | | 72 | V | | 73 | assign_canonical_names() | | 74 | | | | 75 | V | | 76 | parse_docstrings() | | 77 | | | | 78 | V | | 79 | inherit_docs() * | 80 | / | \ | 81 | V V V | 82 | HTMLWriter LaTeXWriter PlaintextWriter * 83 | */ 84 | 85 | ranksep = 0.1; 86 | node [shape="box", height="0", width="0"] 87 | 88 | { /* Task nodes */ 89 | node [fontcolor=\"#000060\"] 90 | introspect [label="Introspect value:\\nintrospect_docs()", 91 | href=""] 92 | parse [label="Parse source code:\\nparse_docs()", 93 | href=""] 94 | merge [label="Merge introspected & parsed docs:\\nmerge_docs()", 95 | href="", width="2.5"] 96 | link [label="Link imports:\\nlink_imports()", 97 | href="", width="2.5"] 98 | name [label="Assign names:\\nassign_canonical_names()", 99 | href="", width="2.5"] 100 | docstrings [label="Parse docstrings:\\nparse_docstring()", 101 | href="", width="2.5"] 102 | inheritance [label="Inherit docs from bases:\\ninherit_docs()", 103 | href="", width="2.5"] 104 | write_html [label="Write HTML output:\\nHTMLWriter", 105 | href=""] 106 | write_latex [label="Write LaTeX output:\\nLaTeXWriter", 107 | href=""] 108 | write_text [label="Write text output:\\nPlaintextWriter", 109 | href=""] 110 | } 111 | 112 | { /* Input & Output nodes */ 113 | node [fontcolor=\"#602000\", shape="plaintext"] 114 | input [label="Python module or value"] 115 | output [label="DocIndex", href=""] 116 | } 117 | 118 | { /* Graph edges */ 119 | edge [fontcolor=\"#602000\"] 120 | input -> introspect 121 | introspect -> merge [label="APIDoc", href=""] 122 | input -> parse 123 | parse -> merge [label="APIDoc", href=""] 124 | merge -> link [label=" DocIndex", href=""] 125 | link -> name [label=" DocIndex", href=""] 126 | name -> docstrings [label=" DocIndex", href=""] 127 | docstrings -> inheritance [label=" DocIndex", href=""] 128 | inheritance -> output 129 | output -> write_html 130 | output -> write_latex 131 | output -> write_text 132 | } 133 | 134 | { /* Task collections */ 135 | node [shape="circle",label="",width=.1,height=.1] 136 | edge [fontcolor="black", dir="none", fontcolor=\"#000060\"] 137 | l3 -> l4 [label=" epydoc.\\l docbuilder.\\l build_doc_index()", 138 | href=""] 139 | l1 -> l2 [label=" epydoc.\\l cli()", href=""] 140 | } 141 | { rank=same; l1 l3 input } 142 | { rank=same; l2 write_html } 143 | { rank=same; l4 output } 144 | 145 | Package Organization 146 | ==================== 147 | The epydoc package contains the following subpackages and modules: 148 | 149 | .. packagetree:: 150 | :style: UML 151 | 152 | The user interfaces are provided by the `gui` and `cli` modules. 153 | The `apidoc` module defines the basic data types used to record 154 | information about Python objects. The programmatic interface to 155 | epydoc is provided by `docbuilder`. Docstring markup parsing is 156 | handled by the `markup` package, and output generation is handled by 157 | the `docwriter` package. See the submodule list for more 158 | information about the submodules and subpackages. 159 | 160 | :group User Interface: gui, cli 161 | :group Basic Data Types: apidoc 162 | :group Documentation Generation: docbuilder, docintrospecter, docparser 163 | :group Docstring Processing: docstringparser, markup 164 | :group Output Generation: docwriter 165 | :group Completeness Checking: checker 166 | :group Miscellaneous: log, util, test, compat 167 | 168 | :author: `Edward Loper `__ 169 | :requires: Python 2.3+ 170 | :version: 3.0.1 171 | :see: `The epydoc webpage `__ 172 | :see: `The epytext markup language 173 | manual `__ 174 | 175 | :todo: Create a better default top_page than trees.html. 176 | :todo: Fix trees.html to work when documenting non-top-level 177 | modules/packages 178 | :todo: Implement @include 179 | :todo: Optimize epytext 180 | :todo: More doctests 181 | :todo: When introspecting, limit how much introspection you do (eg, 182 | don't construct docs for imported modules' vars if it's 183 | not necessary) 184 | 185 | :bug: UserDict.* is interpreted as imported .. why?? 186 | 187 | :license: IBM Open Source License 188 | :copyright: |copy| 2006 Edward Loper 189 | 190 | :newfield contributor: Contributor, Contributors (Alphabetical Order) 191 | :contributor: `Glyph Lefkowitz `__ 192 | :contributor: `Edward Loper `__ 193 | :contributor: `Bruce Mitchener `__ 194 | :contributor: `Jeff O'Halloran `__ 195 | :contributor: `Simon Pamies `__ 196 | :contributor: `Christian Reis `__ 197 | :contributor: `Daniele Varrazzo `__ 198 | :contributor: `Jonathan Guyer `__ 199 | 200 | .. |copy| unicode:: 0xA9 .. copyright sign 201 | """ 202 | __docformat__ = 'restructuredtext en' 203 | 204 | __version__ = '3.0.1' 205 | """The version of epydoc""" 206 | 207 | __author__ = 'Edward Loper ' 208 | """The primary author of eypdoc""" 209 | 210 | __url__ = 'http://epydoc.sourceforge.net' 211 | """The URL for epydoc's homepage""" 212 | 213 | __license__ = 'IBM Open Source License' 214 | """The license governing the use and distribution of epydoc""" 215 | 216 | # [xx] this should probably be a private variable: 217 | DEBUG = False 218 | """True if debugging is turned on.""" 219 | 220 | # Changes needed for docs: 221 | # - document the method for deciding what's public/private 222 | # - epytext: fields are defined slightly differently (@group) 223 | # - new fields 224 | # - document __extra_epydoc_fields__ and @newfield 225 | # - Add a faq? 226 | # - @type a,b,c: ... 227 | # - new command line option: --command-line-order 228 | 229 | -------------------------------------------------------------------------------- /src/epydoc/test/py3/encoding.doctest: -------------------------------------------------------------------------------- 1 | End-to-end Tests for Unicode Encoding 2 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3 | Test Function 4 | ============= 5 | The function `testencoding` is used as an end-to-end test for unicode 6 | encodings. It takes a given string, writes it to a python file, and 7 | processes that file's documentation. It then generates HTML output 8 | from the documentation, extracts all docstrings from the generated 9 | HTML output, and displays them. (In order to extract & display all 10 | docstrings, it monkey-patches the HMTLwriter.docstring_to_html() 11 | method.) 12 | 13 | >>> from epydoc.test.util import testencoding 14 | 15 | >>> from epydoc.test.util import print_warnings 16 | >>> print_warnings() 17 | 18 | Encoding Tests 19 | ============== 20 | This section tests the output for a variety of different encodings. 21 | Note that some encodings (such as cp424) are not supported, since 22 | the ascii coding directive would result in a syntax error in the 23 | new encoding. 24 | 25 | Tests for several Microsoft codepges: 26 | 27 | >>> testencoding(b'''# -*- coding: cp874 -*- 28 | ... """abc ABC 123 \x80 \x85""" 29 | ... ''') 30 |

abc ABC 123 € …

31 | 32 | >>> testencoding(b'''# -*- coding: cp1250 -*- 33 | ... """abc ABC 123 \x80 \x82 \x84 \x85 \xff""" 34 | ... ''') 35 |

abc ABC 123 € ‚ „ … ˙

36 | 37 | >>> testencoding(b'''# -*- coding: cp1251 -*- 38 | ... """abc ABC 123 \x80 \x81 \x82 \xff""" 39 | ... ''') 40 |

abc ABC 123 Ђ Ѓ ‚ я

41 | 42 | >>> testencoding(b'''# -*- coding: cp1252 -*- 43 | ... """abc ABC 123 \x80 \x82 \x83 \xff""" 44 | ... ''') 45 |

abc ABC 123 € ‚ ƒ ÿ

46 | 47 | >>> testencoding(b'''# -*- coding: cp1253 -*- 48 | ... """abc ABC 123 \x80 \x82 \x83 \xfe""" 49 | ... ''') 50 |

abc ABC 123 € ‚ ƒ ώ

51 | 52 | Unicode tests: 53 | 54 | >>> utf8_test = b'''\ 55 | ... """abc ABC 123 56 | ... 57 | ... 0x80-0x7ff range: 58 | ... \xc2\x80 \xc2\x81 \xdf\xbe \xdf\xbf 59 | ... 60 | ... 0x800-0xffff range: 61 | ... \xe0\xa0\x80 \xe0\xa0\x81 \xef\xbf\xbe \xef\xbf\xbf 62 | ... 63 | ... 0x10000-0x10ffff range: 64 | ... \xf0\x90\x80\x80 \xf0\x90\x80\x81 65 | ... \xf4\x8f\xbf\xbe \xf4\x8f\xbf\xbf 66 | ... """\n''' 67 | >>> utf8_bom = b'\xef\xbb\xbf' 68 | 69 | >>> # UTF-8 with a coding directive: 70 | >>> testencoding(b"# -*- coding: utf-8 -*-\n"+utf8_test) 71 |

abc ABC 123

72 |

0x80-0x7ff range: €  ߾ ߿

73 |

0x800-0xffff range: ࠀ ࠁ ￾ ￿

74 |

0x10000-0x10ffff range: 𐀀 𐀁 􏿾 􏿿

75 | 76 | >>> # UTF-8 with a BOM & a coding directive: 77 | >>> testencoding(utf8_bom+b"# -*- coding: utf-8 -*-\n"+utf8_test) 78 |

abc ABC 123

79 |

0x80-0x7ff range: €  ߾ ߿

80 |

0x800-0xffff range: ࠀ ࠁ ￾ ￿

81 |

0x10000-0x10ffff range: 𐀀 𐀁 􏿾 􏿿

82 | 83 | >>> # UTF-8 with a BOM & no coding directive: 84 | >>> testencoding(utf8_bom+utf8_test) 85 |

abc ABC 123

86 |

0x80-0x7ff range: €  ߾ ߿

87 |

0x800-0xffff range: ࠀ ࠁ ￾ ￿

88 |

0x10000-0x10ffff range: 𐀀 𐀁 􏿾 􏿿

89 | 90 | Tests for KOI8-R: 91 | 92 | >>> testencoding(b'''# -*- coding: koi8-r -*- 93 | ... """abc ABC 123 \x80 \x82 \x83 \xff""" 94 | ... ''') 95 |

abc ABC 123 ─ ┌ ┐ Ъ

96 | 97 | Tests for 'coding' directive on the second line: 98 | 99 | >>> testencoding(b'''\n# -*- coding: cp1252 -*- 100 | ... """abc ABC 123 \x80 \x82 \x83 \xff""" 101 | ... ''') 102 |

abc ABC 123 € ‚ ƒ ÿ

103 | 104 | >>> testencoding(b'''# comment on the first line.\n# -*- coding: cp1252 -*- 105 | ... """abc ABC 123 \x80 \x82 \x83 \xff""" 106 | ... ''') 107 |

abc ABC 123 € ‚ ƒ ÿ

108 | 109 | >>> testencoding(b"\n# -*- coding: utf-8 -*-\n"+utf8_test) 110 |

abc ABC 123

111 |

0x80-0x7ff range: €  ߾ ߿

112 |

0x800-0xffff range: ࠀ ࠁ ￾ ￿

113 |

0x10000-0x10ffff range: 𐀀 𐀁 􏿾 􏿿

114 | 115 | >>> testencoding(b"# comment\n# -*- coding: utf-8 -*-\n"+utf8_test) 116 |

abc ABC 123

117 |

0x80-0x7ff range: €  ߾ ߿

118 |

0x800-0xffff range: ࠀ ࠁ ￾ ￿

119 |

0x10000-0x10ffff range: 𐀀 𐀁 􏿾 􏿿

120 | 121 | Tests for shift-jis 122 | 123 | >>> testencoding(b'''# -*- coding: shift_jis -*- 124 | ... """abc ABC 123 \xA1 \xA2 \xA3""" 125 | ... ''') # doctest: +PYTHON2.4 126 |

abc ABC 123 ｡ ｢ ｣

127 | 128 | Str/Unicode Test 129 | ================ 130 | Make sure that we use the coding for both str and unicode docstrings. 131 | 132 | >>> testencoding(b'''# -*- coding: utf-8 -*- 133 | ... """abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80""" 134 | ... ''') 135 |

abc ABC 123 € ߿ ࠀ

136 | 137 | >>> testencoding(b'''# -*- coding: utf-8 -*- 138 | ... """abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80""" 139 | ... ''') 140 |

abc ABC 123 € ߿ ࠀ

141 | 142 | Under special circumstances, we may not be able to tell what the 143 | proper encoding for a docstring is. This happens if: 144 | 145 | 1. the docstring is only available via introspection. 146 | 2. we are unable to determine what module the object that owns 147 | the docstring came from. 148 | 3. the docstring contains non-ascii characters 149 | 150 | Under these circumstances, we issue a warning, and treat the docstring 151 | as latin-1. An example of this is a non-unicode docstring for 152 | properties: 153 | 154 | >>> testencoding(b'''# -*- coding: utf-8 -*- 155 | ... p=property(doc=b"""\\xc2\\x80""") 156 | ... ''') # doctest: +ELLIPSIS 157 | 's docstring is not a unicode string, but it contains non-ascii data -- treating it as latin-1. 158 | € 159 | 160 | Introspection/Parsing Tests 161 | =========================== 162 | This section checks to make sure that both introspection & parsing are 163 | getting the right results. 164 | 165 | >>> testencoding(b"# -*- coding: utf-8 -*-\n"+utf8_test, introspect=False) 166 |

abc ABC 123

167 |

0x80-0x7ff range: €  ߾ ߿

168 |

0x800-0xffff range: ࠀ ࠁ ￾ ￿

169 |

0x10000-0x10ffff range: 𐀀 𐀁 􏿾 􏿿

170 | >>> testencoding(utf8_bom+b"# -*- coding: utf-8 -*-\n"+utf8_test, introspect=False) 171 |

abc ABC 123

172 |

0x80-0x7ff range: €  ߾ ߿

173 |

0x800-0xffff range: ࠀ ࠁ ￾ ￿

174 |

0x10000-0x10ffff range: 𐀀 𐀁 􏿾 􏿿

175 | >>> testencoding(utf8_bom+utf8_test, introspect=False) 176 |

abc ABC 123

177 |

0x80-0x7ff range: €  ߾ ߿

178 |

0x800-0xffff range: ࠀ ࠁ ￾ ￿

179 |

0x10000-0x10ffff range: 𐀀 𐀁 􏿾 􏿿

180 | 181 | >>> testencoding(b"# -*- coding: utf-8 -*-\n"+utf8_test, parse=False) 182 |

abc ABC 123

183 |

0x80-0x7ff range: €  ߾ ߿

184 |

0x800-0xffff range: ࠀ ࠁ ￾ ￿

185 |

0x10000-0x10ffff range: 𐀀 𐀁 􏿾 􏿿

186 | >>> testencoding(utf8_bom+b"# -*- coding: utf-8 -*-\n"+utf8_test, parse=False) 187 |

abc ABC 123

188 |

0x80-0x7ff range: €  ߾ ߿

189 |

0x800-0xffff range: ࠀ ࠁ ￾ ￿

190 |

0x10000-0x10ffff range: 𐀀 𐀁 􏿾 􏿿

191 | >>> testencoding(utf8_bom+utf8_test, parse=False) 192 |

abc ABC 123

193 |

0x80-0x7ff range: €  ߾ ߿

194 |

0x800-0xffff range: ࠀ ࠁ ￾ ￿

195 |

0x10000-0x10ffff range: 𐀀 𐀁 􏿾 􏿿

196 | 197 | Context checks 198 | ============== 199 | Make sure that docstrings are rendered correctly in different contexts. 200 | 201 | >>> testencoding(b'''# -*- coding: utf-8 -*- 202 | ... """ 203 | ... @var x: abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80 204 | ... @group \xc2\x80: x 205 | ... """ 206 | ... ''') 207 | abc ABC 123 € ߿ ࠀ 208 | 209 | >>> testencoding(b'''# -*- coding: utf-8 -*- 210 | ... def f(x): 211 | ... """ 212 | ... abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80 213 | ... @param x: abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80 214 | ... @type x: abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80 215 | ... @return: abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80 216 | ... @rtype: abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80 217 | ... @except X: abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80 218 | ... """ 219 | ... ''') 220 | abc ABC 123 € ߿ ࠀ 221 | abc ABC 123 € ߿ ࠀ 222 |

abc ABC 123 € ߿ ࠀ

223 | abc ABC 123 € ߿ ࠀ 224 | abc ABC 123 € ߿ ࠀ 225 | abc ABC 123 € ߿ ࠀ 226 | abc ABC 123 € ߿ ࠀ 227 | abc ABC 123 € ߿ ࠀ 228 | 229 | >>> testencoding(b'''# -*- coding: utf-8 -*- 230 | ... class A: 231 | ... """ 232 | ... abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80 233 | ... @ivar x: abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80 234 | ... @cvar y: abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80 235 | ... @type x: abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80 236 | ... """ 237 | ... 238 | ... z = property(doc="abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80") 239 | ... ''') 240 | abc ABC 123 € ߿ ࠀ 241 |

abc ABC 123 € ߿ ࠀ

242 | abc ABC 123 € ߿ ࠀ 243 | abc ABC 123 € ߿ ࠀ 244 | abc ABC 123 € ߿ ࠀ 245 | abc ABC 123 € ߿ ࠀ 246 | 247 | 248 | 249 | 250 | 251 | 252 | 253 | -------------------------------------------------------------------------------- /src/epydoc/test/py2/encoding.doctest: -------------------------------------------------------------------------------- 1 | End-to-end Tests for Unicode Encoding 2 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3 | Test Function 4 | ============= 5 | The function `testencoding` is used as an end-to-end test for unicode 6 | encodings. It takes a given string, writes it to a python file, and 7 | processes that file's documentation. It then generates HTML output 8 | from the documentation, extracts all docstrings from the generated 9 | HTML output, and displays them. (In order to extract & display all 10 | docstrings, it monkey-patches the HMTLwriter.docstring_to_html() 11 | method.) 12 | 13 | >>> from epydoc.test.util import testencoding 14 | 15 | >>> from epydoc.test.util import print_warnings 16 | >>> print_warnings() 17 | 18 | Encoding Tests 19 | ============== 20 | This section tests the output for a variety of different encodings. 21 | Note that some encodings (such as cp424) are not supported, since 22 | the ascii coding directive would result in a syntax error in the 23 | new encoding. 24 | 25 | Tests for several Microsoft codepges: 26 | 27 | >>> testencoding('''# -*- coding: cp874 -*- 28 | ... """abc ABC 123 \x80 \x85""" 29 | ... ''') 30 |

abc ABC 123 € …

31 | 32 | >>> testencoding('''# -*- coding: cp1250 -*- 33 | ... """abc ABC 123 \x80 \x82 \x84 \x85 \xff""" 34 | ... ''') 35 |

abc ABC 123 € ‚ „ … ˙

36 | 37 | >>> testencoding('''# -*- coding: cp1251 -*- 38 | ... """abc ABC 123 \x80 \x81 \x82 \xff""" 39 | ... ''') 40 |

abc ABC 123 Ђ Ѓ ‚ я

41 | 42 | >>> testencoding('''# -*- coding: cp1252 -*- 43 | ... """abc ABC 123 \x80 \x82 \x83 \xff""" 44 | ... ''') 45 |

abc ABC 123 € ‚ ƒ ÿ

46 | 47 | >>> testencoding('''# -*- coding: cp1253 -*- 48 | ... """abc ABC 123 \x80 \x82 \x83 \xfe""" 49 | ... ''') 50 |

abc ABC 123 € ‚ ƒ ώ

51 | 52 | Unicode tests: 53 | 54 | >>> utf8_test ='''\ 55 | ... """abc ABC 123 56 | ... 57 | ... 0x80-0x7ff range: 58 | ... \\xc2\\x80 \\xc2\\x81 \\xdf\\xbe \\xdf\\xbf 59 | ... 60 | ... 0x800-0xffff range: 61 | ... \\xe0\\xa0\\x80 \\xe0\\xa0\\x81 \\xef\\xbf\\xbe \\xef\\xbf\\xbf 62 | ... 63 | ... 0x10000-0x10ffff range: 64 | ... \\xf0\\x90\\x80\\x80 \\xf0\\x90\\x80\\x81 65 | ... \\xf4\\x8f\\xbf\\xbe \\xf4\\x8f\\xbf\\xbf 66 | ... """\n''' 67 | >>> utf8_bom = '\xef\xbb\xbf' 68 | 69 | >>> # UTF-8 with a coding directive: 70 | >>> testencoding("# -*- coding: utf-8 -*-\n"+utf8_test) 71 |

abc ABC 123

72 |

0x80-0x7ff range: €  ߾ ߿

73 |

0x800-0xffff range: ࠀ ࠁ ￾ ￿

74 |

0x10000-0x10ffff range: 𐀀 𐀁 􏿾 􏿿

75 | 76 | >>> # UTF-8 with a BOM & a coding directive: 77 | >>> testencoding(utf8_bom+"# -*- coding: utf-8 -*-\n"+utf8_test) 78 |

abc ABC 123

79 |

0x80-0x7ff range: €  ߾ ߿

80 |

0x800-0xffff range: ࠀ ࠁ ￾ ￿

81 |

0x10000-0x10ffff range: 𐀀 𐀁 􏿾 􏿿

82 | 83 | >>> # UTF-8 with a BOM & no coding directive: 84 | >>> testencoding(utf8_bom+utf8_test) 85 |

abc ABC 123

86 |

0x80-0x7ff range: €  ߾ ߿

87 |

0x800-0xffff range: ࠀ ࠁ ￾ ￿

88 |

0x10000-0x10ffff range: 𐀀 𐀁 􏿾 􏿿

89 | 90 | Tests for KOI8-R: 91 | 92 | >>> testencoding('''# -*- coding: koi8-r -*- 93 | ... """abc ABC 123 \x80 \x82 \x83 \xff""" 94 | ... ''') 95 |

abc ABC 123 ─ ┌ ┐ Ъ

96 | 97 | Tests for 'coding' directive on the second line: 98 | 99 | >>> testencoding('''\n# -*- coding: cp1252 -*- 100 | ... """abc ABC 123 \x80 \x82 \x83 \xff""" 101 | ... ''') 102 |

abc ABC 123 € ‚ ƒ ÿ

103 | 104 | >>> testencoding('''# comment on the first line.\n# -*- coding: cp1252 -*- 105 | ... """abc ABC 123 \x80 \x82 \x83 \xff""" 106 | ... ''') 107 |

abc ABC 123 € ‚ ƒ ÿ

108 | 109 | >>> testencoding("\n# -*- coding: utf-8 -*-\n"+utf8_test) 110 |

abc ABC 123

111 |

0x80-0x7ff range: €  ߾ ߿

112 |

0x800-0xffff range: ࠀ ࠁ ￾ ￿

113 |

0x10000-0x10ffff range: 𐀀 𐀁 􏿾 􏿿

114 | 115 | >>> testencoding("# comment\n# -*- coding: utf-8 -*-\n"+utf8_test) 116 |

abc ABC 123

117 |

0x80-0x7ff range: €  ߾ ߿

118 |

0x800-0xffff range: ࠀ ࠁ ￾ ￿

119 |

0x10000-0x10ffff range: 𐀀 𐀁 􏿾 􏿿

120 | 121 | Tests for shift-jis 122 | 123 | >>> testencoding('''# -*- coding: shift_jis -*- 124 | ... """abc ABC 123 \xA1 \xA2 \xA3""" 125 | ... ''') # doctest: +PYTHON2.4 126 |

abc ABC 123 ｡ ｢ ｣

127 | 128 | Str/Unicode Test 129 | ================ 130 | Make sure that we use the coding for both str and unicode docstrings. 131 | 132 | >>> testencoding('''# -*- coding: utf-8 -*- 133 | ... """abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80""" 134 | ... ''') 135 |

abc ABC 123 € ߿ ࠀ

136 | 137 | >>> testencoding('''# -*- coding: utf-8 -*- 138 | ... u"""abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80""" 139 | ... ''') 140 |

abc ABC 123 € ߿ ࠀ

141 | 142 | Under special circumstances, we may not be able to tell what the 143 | proper encoding for a docstring is. This happens if: 144 | 145 | 1. the docstring is only available via introspection. 146 | 2. we are unable to determine what module the object that owns 147 | the docstring came from. 148 | 3. the docstring contains non-ascii characters 149 | 150 | Under these circumstances, we issue a warning, and treat the docstring 151 | as latin-1. An example of this is a non-unicode docstring for 152 | properties: 153 | 154 | >>> testencoding('''# -*- coding: utf-8 -*- 155 | ... p=property(doc="""\\xc2\\x80""") 156 | ... ''') # doctest: +ELLIPSIS 157 | 's docstring is not a unicode string, but it contains non-ascii data -- treating it as latin-1. 158 | € 159 | 160 | Introspection/Parsing Tests 161 | =========================== 162 | This section checks to make sure that both introspection & parsing are 163 | getting the right results. 164 | 165 | >>> testencoding("# -*- coding: utf-8 -*-\n"+utf8_test, introspect=False) 166 |

abc ABC 123

167 |

0x80-0x7ff range: €  ߾ ߿

168 |

0x800-0xffff range: ࠀ ࠁ ￾ ￿

169 |

0x10000-0x10ffff range: 𐀀 𐀁 􏿾 􏿿

170 | >>> testencoding(utf8_bom+"# -*- coding: utf-8 -*-\n"+utf8_test, introspect=False) 171 |

abc ABC 123

172 |

0x80-0x7ff range: €  ߾ ߿

173 |

0x800-0xffff range: ࠀ ࠁ ￾ ￿

174 |

0x10000-0x10ffff range: 𐀀 𐀁 􏿾 􏿿

175 | >>> testencoding(utf8_bom+utf8_test, introspect=False) 176 |

abc ABC 123

177 |

0x80-0x7ff range: €  ߾ ߿

178 |

0x800-0xffff range: ࠀ ࠁ ￾ ￿

179 |

0x10000-0x10ffff range: 𐀀 𐀁 􏿾 􏿿

180 | 181 | >>> testencoding("# -*- coding: utf-8 -*-\n"+utf8_test, parse=False) 182 |

abc ABC 123

183 |

0x80-0x7ff range: €  ߾ ߿

184 |

0x800-0xffff range: ࠀ ࠁ ￾ ￿

185 |

0x10000-0x10ffff range: 𐀀 𐀁 􏿾 􏿿

186 | >>> testencoding(utf8_bom+"# -*- coding: utf-8 -*-\n"+utf8_test, parse=False) 187 |

abc ABC 123

188 |

0x80-0x7ff range: €  ߾ ߿

189 |

0x800-0xffff range: ࠀ ࠁ ￾ ￿

190 |

0x10000-0x10ffff range: 𐀀 𐀁 􏿾 􏿿

191 | >>> testencoding(utf8_bom+utf8_test, parse=False) 192 |

abc ABC 123

193 |

0x80-0x7ff range: €  ߾ ߿

194 |

0x800-0xffff range: ࠀ ࠁ ￾ ￿

195 |

0x10000-0x10ffff range: 𐀀 𐀁 􏿾 􏿿

196 | 197 | Context checks 198 | ============== 199 | Make sure that docstrings are rendered correctly in different contexts. 200 | 201 | >>> testencoding('''# -*- coding: utf-8 -*- 202 | ... """ 203 | ... @var x: abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80 204 | ... @group \xc2\x80: x 205 | ... """ 206 | ... ''') 207 | abc ABC 123 € ߿ ࠀ 208 | 209 | >>> testencoding('''# -*- coding: utf-8 -*- 210 | ... def f(x): 211 | ... """ 212 | ... abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80 213 | ... @param x: abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80 214 | ... @type x: abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80 215 | ... @return: abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80 216 | ... @rtype: abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80 217 | ... @except X: abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80 218 | ... """ 219 | ... ''') 220 | abc ABC 123 € ߿ ࠀ 221 | abc ABC 123 € ߿ ࠀ 222 |

abc ABC 123 € ߿ ࠀ

223 | abc ABC 123 € ߿ ࠀ 224 | abc ABC 123 € ߿ ࠀ 225 | abc ABC 123 € ߿ ࠀ 226 | abc ABC 123 € ߿ ࠀ 227 | abc ABC 123 € ߿ ࠀ 228 | 229 | >>> testencoding('''# -*- coding: utf-8 -*- 230 | ... class A: 231 | ... """ 232 | ... abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80 233 | ... @ivar x: abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80 234 | ... @cvar y: abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80 235 | ... @type x: abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80 236 | ... """ 237 | ... 238 | ... z = property(doc=u"abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80") 239 | ... ''') 240 | abc ABC 123 € ߿ ࠀ 241 |

abc ABC 123 € ߿ ࠀ

242 | abc ABC 123 € ߿ ࠀ 243 | abc ABC 123 € ߿ ࠀ 244 | abc ABC 123 € ߿ ࠀ 245 | abc ABC 123 € ߿ ࠀ 246 | 247 | 248 | 249 | 250 | 251 | 252 | 253 | -------------------------------------------------------------------------------- /doc/installing.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | Installing Epydoc 4 | 5 | 6 | 7 | 8 | 9 |
10 |

Installing Epydoc

11 | 12 |

Contents

13 |
    14 |
  1. Downloading Epydoc
    2. 15 |
  2. Getting Epydoc from Subversion
    3. 16 |
  3. Installing from the RPM File
    4. 17 |
  4. Installing from the Windows Installer
    5. 18 |
  5. Installing from the Source Distribution
    6. 19 |
  6. Installing from the Source Distribution (without 20 | make)
    7. 21 |
  7. Installing on Debian
    8. 22 |
23 |
24 | 25 | 26 |

Downloading Epydoc

27 | 28 |

Epydoc can be downloaded from the SourceForge 30 | download page. Epydoc is available in five formats:

31 |
    32 |
  • RPM (.noarch.rpm)
    • 33 |
  • Windows installer (.win32.exe)
    • 34 |
  • Source install (.tar.gz)
    • 35 |
  • Source install (.zip)
    • 36 |
  • Source RPM (.src.rpm)
    • 37 |
38 | 39 |

If you are installing on RedHat, I recommend that you use the RPM 40 | file. If you are installing on Windows, I recommended that you use 41 | the windows installer. Otherwise, you should use one of the source 42 | install files.

43 | 44 | 45 |

Getting Epydoc from Subversion

46 | 47 |

If you wish to keep up on the latest developments, you can get the 48 | latest version of epydoc from the subversion 50 | repository:

51 | 52 | 
 53 | [/home/edloper]$ svn co https://epydoc.svn.sourceforge.net/svnroot/epydoc/trunk/epydoc epydoc
 54 | [/home/edloper]$ ls epydoc
 55 | Makefile  doc  man  sandbox  src
 56 |
57 |
58 | 59 |

This will create a directory named epydoc containing 60 | the latest version of epydoc. The epydoc package itself is in 61 | epydoc/src/epydoc (so adding epydoc/src to 62 | your PYTHONPATH will let you use it). You should periodically update 63 | your copy of the subversion repository, to make sure you have all the 64 | latest changes: 65 | 66 | 

 67 | [/home/edloper/epydoc]$ svn up
 68 |
69 |
70 | 71 |

You can browse the subversion repository here.

73 | 74 | 75 | 76 |

Installing from the RPM File

77 | 78 |
    79 |
  1. Download the RPM file to a directory of your choice. 80 | 81 |
  2. Use rpm to install the new package. 82 | 83 | 
     84 | [/tmp]$ su
 85 | Password:
 86 | [/tmp]# rpm -i epydoc-3.0.1.noarch.rpm
 87 |
    3. 88 | 89 |
  3. Once epydoc is installed, you can delete the RPM file. 90 | 91 | 
     92 | [/tmp]# rm epydoc-3.0.1.rpm
 93 |
    4. 94 |
95 | 96 | 97 |

Installing from the Windows Installer

98 | 99 |
    100 |
  1. Download and run epydoc-3.0.1.win32.exe.
    2. 101 |
  2. Follow the on-screen instructions. Epydoc will be installed in 102 | the epydoc subdirectory of your Python installation 103 | directory (typically C:\Python23\).
    3. 104 |
  3. The windows installer creates two scripts in the 105 | Scripts subdirectory of your Python installation 106 | directory: epydoc.pyw opens the graphical user 107 | interface, and epydoc.py calls the command line 108 | interface. If you'd like, you can create shortcuts from these 109 | scripts to more convenient locations (such as your desktop or start 110 | menu).
    4. 111 |
  4. Once epydoc is installed, you can delete 112 | epydoc-3.0.1.win32.exe.
    5. 113 |
114 | 115 | 116 |

Installing from the Source Distribution (using make)

117 | 118 |
    119 |
  1. Download an epydoc source distribution 120 | to a directory of your choice, and uncompress it. 121 | 122 | 
    123 | [/tmp]$ wget -q http://prdownloads.sourceforge.net/epydoc/epydoc-3.0.1.tar.gz
124 | [/tmp]$ gunzip epydoc-3.0.1.tar.gz
125 | [/tmp]$ tar -xvf epydoc-3.0.1.tar
126 |
    2. 127 | 128 |
  2. Use "make install" in the eydoc-3.0.1/ 129 | directory to install epydoc. 130 | 131 | 
    132 | [/tmp]$ cd epydoc-3.0.1/
133 | [/tmp/epydoc-3.0.1]$ su
134 | Password:
135 | [/tmp/epydoc-3.0.1]# make install
136 | running install
137 | running build
138 | [...]
139 | copying build/scripts/epydoc -> /usr/bin
140 | changing mode of /usr/bin/epydoc to 100775
141 |
    3. 142 | 143 |
  3. If you'd like to keep a local copy of the documentation, then use 144 | "make installdocs". By default, this will install the 145 | documentation to /usr/share/doc/ and the man pages to 146 | /usr/share/man/. If you would prefer to install 147 | documentation to different directories (such as 148 | /usr/lib/doc), then edit the MAN and 149 | DOC variables at the top of Makefile before 150 | running "make installdocs". 151 | 152 | 
    153 | [/tmp/epydoc-3.0.1]# make installdocs
154 |
    4. 155 | 156 |
  4. Once epydoc is installed, you can delete the installation 157 | directory and the source distribution file. 158 | 159 | 
    160 | [/tmp/epydoc-3.0.1]# cd ..
161 | [/tmp]# rm -r epydoc-3.0.1
162 | [/tmp]# rm epydoc-3.0.1.tar
163 |
    5. 164 |
165 | 166 | 167 |

Installing from the Source Distribution (without make)

168 | 169 |
    170 |
  1. Download an epydoc source distribution 171 | to a directory of your choice, and uncompress it. 172 | 173 | 
    174 | [/tmp]$ wget -q http://prdownloads.sourceforge.net/epydoc/epydoc-3.0.1.tar.gz
175 | [/tmp]$ gunzip epydoc-3.0.1.tar.gz
176 | [/tmp]$ tar -xvf epydoc-3.0.1.tar
177 |
    2. 178 | 179 |
  2. Use the setup.py script in the 180 | eydoc-3.0.1/ directory to install epydoc. 181 | 182 | 
    183 | [/tmp]$ cd epydoc-3.0.1/
184 | [/tmp/epydoc-3.0.1]$ su
185 | Password:
186 | [/tmp/epydoc-3.0.1]# python setup.py install
187 | running install
188 | running build
189 | [...]
190 | copying build/scripts/epydoc -> /usr/bin
191 | changing mode of /usr/bin/epydoc to 100775
192 | [/tmp/epydoc-3.0.1]# cd ..
193 | [/tmp]#
194 |
    3. 195 | 196 |
  3. If you'd like to keep a local copy of the documentation, then 197 | copy it to a permanant location, such as /usr/share/doc/. 198 | You may also want to copy the man pages to a permanant location, such 199 | as /usr/share/man/. 200 | 201 | 
    202 | [/tmp]# cp -r epydoc-3.0.1/doc/ /usr/share/doc/epydoc/
203 | [/tmp]# cp epydoc-3.0.1/man/* /usr/share/man/
204 |
    4. 205 | 206 |
  4. Once epydoc is installed, you can delete the installation 207 | directory and the source distribution file. 208 | 209 | 
    210 | [/tmp]# rm -r epydoc-3.0.1
211 | [/tmp]# rm epydoc-3.0.1.tar
212 |
    5. 213 |
214 | 215 | 216 |

Installing on Debian

217 | 218 |

Epydoc 2.1 is available as a testing debian package 219 | (python-epydoc). The epydoc documentation is also 220 | available as a package (epydoc-doc).

221 | 222 |
223 | 224 | 225 | 226 | 229 | 230 | 233 | 234 | 237 | 238 | 241 | 247 | 248 |
227 | 228 | Home 231 | 232 | Installing Epydoc 235 | 236 | Using Epydoc 239 | 240 | Epytext 242 | 243 | 244 | SourceForge
249 | 250 | 251 | --------------------------------------------------------------------------------