[Epydoc-commits] SF.net SVN: epydoc: [1547] trunk/epydoc

[<dva...@us...>]

Revision: 1547
          http://svn.sourceforge.net/epydoc/?rev=1547&view=rev
Author:   dvarrazzo
Date:     2007-02-21 09:34:54 -0800 (Wed, 21 Feb 2007)

Log Message:
-----------
- The manual can be created both as a single document and many pages.
  The single chapters may be linked from the homepage.

Modified Paths:
--------------
    trunk/epydoc/Makefile
    trunk/epydoc/doc/manual-epytext.txt
    trunk/epydoc/doc/manual-othermarkup.txt
    trunk/epydoc/doc/manual-reference.txt
    trunk/epydoc/doc/manual.txt
    trunk/epydoc/src/tools/rst2html.py

Added Paths:
-----------
    trunk/epydoc/src/tools/mkdispatch.py

Property Changed:
----------------
    trunk/epydoc/doc/

Modified: trunk/epydoc/Makefile
===================================================================
--- trunk/epydoc/Makefile	2007-02-20 23:51:34 UTC (rev 1546)
+++ trunk/epydoc/Makefile	2007-02-21 17:34:54 UTC (rev 1547)
@@ -14,7 +14,7 @@
 EXAMPLES_SRC = $(wildcard doc/*.py)
 DOCS = $(wildcard doc/*)
 DOCTESTS = $(wildcard src/epydoc/test/*.doctest)
-MANUAL_SRC = $(wildcard doc/manual*.txt)
+MANUAL_SRC = $(wildcard doc/manual-*.txt)
 
 # What version of python to use?
 PYTHON = python
@@ -32,6 +32,7 @@
 HTML          = html
 
 # Output subdirectories
+HTML_MANUAL   = $(HTML)
 HTML_API      = $(HTML)/api
 HTML_EXAMPLES = $(HTML)/examples
 HTML_STDLIB   = $(HTML)/stdlib
@@ -44,12 +45,13 @@
 
 # Options for rst->html converter
 RST2HTML = $(PYTHON) src/tools/rst2html.py
+MKDISPATCH = $(PYTHON) src/tools/mkdispatch.py
 
 DOCTEST_HTML_FILES := \
     $(DOCTESTS:src/epydoc/test/%.doctest=$(HTML_DOCTEST)/%.html)
 
-manual-html: $(MANUAL_SRC)
-	$(RST2HTML) doc/manual.txt $(HTML)/epydoc.html
+MANUAL_HTML_FILES := $(HTML_MANUAL)/epydoc.html \
+    $(MANUAL_SRC:doc/manual-%.txt=$(HTML_MANUAL)/manual-%.html)
 
 ##//////////////////////////////////////////////////////////////////////
 ## Usage
@@ -106,16 +108,29 @@
 	rm -rf /var/www/epydoc/*
 	cp -r $(WEBDIR)/* /var/www/epydoc
 
+manual-html: $(MANUAL_HTML_FILES)
+
+$(HTML_MANUAL)/epydoc.html: doc/manual.txt $(MANUAL_SRC)
+	$(RST2HTML) doc/manual.txt $@
+
+$(HTML_MANUAL)/manual-%.html: doc/manual-%.txt
+	echo .. contents::               > doc/tmp.txt
+	echo .. include:: ../$<         >> doc/tmp.txt
+	$(MKDISPATCH) $(MANUAL_SRC)     >> doc/tmp.txt
+	$(RST2HTML) doc/tmp.txt $@
+	
 checkdoc: checkdocs
 checkdocs:
 	epydoc --check --tests=vars,types $(PY_SRC)
 
 .webpage.up2date: .api-html.up2date .examples.up2date .api-pdf.up2date \
 		$(DOCTEST_HTML_FILES) doc/epydoc-man.html \
-		doc/epydocgui-man.html $(DOCS)
+		doc/epydocgui-man.html $(DOCS) $(MANUAL_HTML_FILES)
 	rm -rf $(WEBDIR)
 	mkdir -p $(WEBDIR)
 	cp -r $(DOCS) $(WEBDIR)
+	cp -r $(HTML_MANUAL)/epydoc.html $(WEBDIR)
+	cp -r $(HTML_MANUAL)/manual*.html $(WEBDIR)
 	cp -r $(HTML_API) $(WEBDIR)/api
 	cp -r $(HTML_EXAMPLES) $(WEBDIR)/examples
 	cp -r $(HTML_DOCTEST)/* $(WEBDIR)/doctest
@@ -151,7 +166,7 @@
 	mkdir -p $(HTML_DOCTEST)
 $(HTML_DOCTEST)/%.html: src/epydoc/test/%.doctest
 	mkdir -p $(HTML_DOCTEST)
-	$(RST2HTML) $< $@
+	$(RST2HTML) --stylesheet=../custom.css $< $@
 
 examples: .examples.up2date
 .examples.up2date: $(EXAMPLES_SRC) $(PY_SRCFILES)


Property changes on: trunk/epydoc/doc
___________________________________________________________________
Name: svn:ignore
   - *-man.html
api
*.pyc
examples
   + *-man.html
api
*.pyc
tmp.txt
examples


Modified: trunk/epydoc/doc/manual-epytext.txt
===================================================================
--- trunk/epydoc/doc/manual-epytext.txt	2007-02-20 23:51:34 UTC (rev 1546)
+++ trunk/epydoc/doc/manual-epytext.txt	2007-02-21 17:34:54 UTC (rev 1547)
@@ -3,9 +3,58 @@
 
 .. $Id$
 
-Overview
---------
+A Brief Introduction
+--------------------
 
+Epytext is a simple lightweight markup language that lets you add formatting
+and structue to docstrings. Epydoc uses that formatting and structure to
+produce nicely formatted API documentation. The following example (which has
+an unusually high ratio of documentaiton to code) illustrates some of the
+basic features of epytext:
+
+.. python::
+
+    def x_intercept(m, b):
+        """
+        Return the x intercept of the line M{y=m*x+b}.  The X{x intercept}
+        of a line is the point at which it crosses the x axis (M{y=0}).
+
+        This function can be used in conjuction with L{z_transform} to
+        find an arbitrary function's zeros.
+
+        @type  m: number
+        @param m: The slope of the line.
+        @type  b: number
+        @param b: The y intercept of the line.  The X{y intercept} of a
+                  line is the point at which it crosses the y axis (M{x=0}).
+        @rtype:   number
+        @return:  the x intercept of the line M{y=m*x+b}.
+        """
+	return -b/m
+
+You can compare this function definition with the `API documentation`__
+generated by epydoc. Note that:
+
+* Paragraphs are separated by blank lines.
+* Inline markup has the form "*x*\ ``{``\ ...\ ``}``", where "*x*" is a 
+  single capital letter. This example uses inline markup to mark mathematical 
+  expressions ("``M{...}``"); terms that should be indexed ("``X{...}``"); 
+  and links to the documentation of other objects ("``L{...}``").
+* Descriptions of parameters, return values, and types are marked with 
+  "``@``\ *field*\ ``:``" or "``@``\ *field arg*\ ``:``", where "*field*" 
+  identifies the kind of description, and "*arg*" specifies what object is 
+  described.
+
+.. __: http://epydoc.sourceforge.net/
+       examples/epytext_example-module.html#x_intercept
+
+Epytext is intentionally very lightweight. If you wish to use a more
+expressive markup language, I recommend reStructuredText_.
+
+
+Epytext Language Overview
+-------------------------
+
 Epytext is a lightweight markup language for Python docstrings. The epytext
 markup language is used by epydoc to parse docstrings and create structured API
 documentation. Epytext markup is broken up into the following categories:

Modified: trunk/epydoc/doc/manual-othermarkup.txt
===================================================================
--- trunk/epydoc/doc/manual-othermarkup.txt	2007-02-20 23:51:34 UTC (rev 1546)
+++ trunk/epydoc/doc/manual-othermarkup.txt	2007-02-21 17:34:54 UTC (rev 1547)
@@ -3,11 +3,13 @@
 
 .. $Id$
 
-Epydoc's default markup language is epytext_, a lightweight markup language
+Epydoc's default markup language is epytext__, a lightweight markup language
 that's easy to write and to understand. But if epytext is not powerful enough
 for you, or doesn't suit your needs, epydoc also supports three alternate
 markup languages:
 
+.. __: `The Epytext Markup Language`_
+
 reStructuredText__
     is an "easy-to-read, what-you-see-is-what-you-get plaintext markup syntax".
     It is more powerful than epytext (e.g., it includes markup for tables and

Modified: trunk/epydoc/doc/manual-reference.txt
===================================================================
--- trunk/epydoc/doc/manual-reference.txt	2007-02-20 23:51:34 UTC (rev 1546)
+++ trunk/epydoc/doc/manual-reference.txt	2007-02-21 17:34:54 UTC (rev 1547)
@@ -140,6 +140,8 @@
 various options that you can set. Lines beginning with ``#`` or ``;`` are
 treated as comments.
 
+.. _ConfigParser: http://docs.python.org/lib/module-ConfigParser.html
+
 .. parsed-literal::
 
     **[epydoc]** *# Epydoc section marker (required by ConfigParser)*

Modified: trunk/epydoc/doc/manual.txt
===================================================================
--- trunk/epydoc/doc/manual.txt	2007-02-20 23:51:34 UTC (rev 1546)
+++ trunk/epydoc/doc/manual.txt	2007-02-21 17:34:54 UTC (rev 1547)
@@ -25,7 +25,7 @@
 
 .. _html:       http://epydoc.sourceforge.net/api/
 .. _pdf:        http://epydoc.sourceforge.net/epydoc.pdf
-.. _epytext:    http://epydoc.sourceforge.net/epytextintro.html
+.. _epytext:    `The Epytext Markup Language`_
 .. _reStructuredText:
                 http://docutils.sourceforge.net/rst.html
 .. _JavaDoc:    http://java.sun.com/j2se/javadoc/

Added: trunk/epydoc/src/tools/mkdispatch.py
===================================================================
--- trunk/epydoc/src/tools/mkdispatch.py	                        (rev 0)
+++ trunk/epydoc/src/tools/mkdispatch.py	2007-02-21 17:34:54 UTC (rev 1547)
@@ -0,0 +1,48 @@
+#!/usr/bin/env python
+# -*- coding: iso-8859-1 -*-
+"""A tool to allow creation of both single page and multi-page manual.
+
+For each file name in argv, detect title names and print a directive
+referring to it as anchor in an html file.
+"""
+
+# $Id$
+__version__ = "$Revision$"[11:-2]
+__author__ = "Daniele Varrazzo"
+__copyright__ = "Copyright (C) 2007 by Daniele Varrazzo"
+
+import sys, os
+
+def parse_pairs(fn):
+    """Parse a file and return a list of directives to create links."""
+    outfile = os.path.splitext(os.path.split(fn)[1])[0] + '.html'
+    rv = []
+    prev = None
+    for curr in open(fn):
+        curr = curr.rstrip()
+        if prev is not None: 
+            if curr and curr[0] in "'^-=~":
+                if curr == curr[0] * len(curr):
+                    rv.append(".. _%s: %s#%s" % 
+                        (prev, outfile, get_anchor(prev)))
+        prev = curr
+
+    return rv
+
+import string
+charmap = {}
+charmap.update(zip(string.ascii_lowercase, string.ascii_lowercase))
+charmap.update(zip(string.ascii_uppercase, string.ascii_lowercase))
+charmap[' '] = '-'
+for k in '()':
+    charmap[k] = ''
+
+def get_anchor(s):
+    # IndexErrors are expected to test for what else include in the map
+    return "".join(map(charmap.__getitem__, s))
+
+if __name__ == '__main__':
+    for fn in sys.argv[1:]:
+        for dir in parse_pairs(fn):
+            print dir
+


Property changes on: trunk/epydoc/src/tools/mkdispatch.py
___________________________________________________________________
Name: svn:executable
   + *
Name: svn:keywords
   + Id Revision
Name: svn:eol-style
   + native

Modified: trunk/epydoc/src/tools/rst2html.py
===================================================================
--- trunk/epydoc/src/tools/rst2html.py	2007-02-20 23:51:34 UTC (rev 1546)
+++ trunk/epydoc/src/tools/rst2html.py	2007-02-21 17:34:54 UTC (rev 1547)
@@ -32,9 +32,9 @@
 class CustomizedHTMLWriter(HTMLWriter):
     settings_defaults = (HTMLWriter.settings_defaults or {}).copy()
     settings_defaults.update({
-        'stylesheet_path': os.path.normpath(os.path.join(
-            os.path.split(__file__)[0], '../../doc/custom.css')),
-            'output_encoding': 'ascii',
+        'stylesheet': 'custom.css',
+        'stylesheet_path': None,
+        'output_encoding': 'ascii',
         'output_encoding_error_handler': 'xmlcharrefreplace',
         'embed_stylesheet': False,
         })


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.