Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
[svn r3575] r4037@delle: sbehnel | 2008-04-23 18:15:02 +0200
 include generated API documentation in PDF

--HG--
branch : trunk
  • Loading branch information
scoder committed Apr 23, 2008
1 parent 6edfe7e commit d309884
Show file tree
Hide file tree
Showing 2 changed files with 102 additions and 25 deletions.
21 changes: 17 additions & 4 deletions Makefile
Expand Up @@ -41,17 +41,30 @@ ftest_build: build
ftest_inplace: inplace ftest_inplace: inplace
$(PYTHON) test.py -f $(TESTFLAGS) $(TESTOPTS) $(PYTHON) test.py -f $(TESTFLAGS) $(TESTOPTS)


html: inplace apihtml: inplace
PYTHONPATH=src $(PYTHON) doc/mkhtml.py doc/html . ${LXMLVERSION}
rm -fr doc/html/api rm -fr doc/html/api
@[ -x "`which epydoc`" ] \ @[ -x "`which epydoc`" ] \
&& (cd src && echo "Generating API docs ..." && \ && (cd src && echo "Generating API docs ..." && \
PYTHONPATH=. epydoc -v --docformat "restructuredtext en" \ PYTHONPATH=. epydoc -v --docformat "restructuredtext en" \
-o ../doc/html/api --no-private --exclude='[.]html[.]tests|[.]_' \ -o ../doc/html/api --no-private --exclude='[.]html[.]tests|[.]_' \
--name lxml --url http://codespeak.net/lxml/ lxml/) \ --name "lxml API" --url http://codespeak.net/lxml/ lxml/) \
|| (echo "not generating epydoc API documentation")

html: inplace apihtml
PYTHONPATH=src $(PYTHON) doc/mkhtml.py doc/html . ${LXMLVERSION}

apipdf: inplace
rm -fr doc/pdf
mkdir -p doc/pdf
@[ -x "`which epydoc`" ] \
&& (cd src && echo "Generating API docs ..." && \
PYTHONPATH=. epydoc -v --latex --docformat "restructuredtext en" \
-o ../doc/pdf --no-private --exclude='([.]html)?[.]tests|[.]_' \
--exclude-introspect='html[.]clean' \
--name "lxml API" --url http://codespeak.net/lxml/ lxml/) \
|| (echo "not generating epydoc API documentation") || (echo "not generating epydoc API documentation")


pdf: pdf: apipdf
$(PYTHON) doc/mklatex.py doc/pdf . ${LXMLVERSION} $(PYTHON) doc/mklatex.py doc/pdf . ${LXMLVERSION}
(cd doc/pdf && pdflatex lxmldoc.tex && pdflatex lxmldoc.tex) (cd doc/pdf && pdflatex lxmldoc.tex && pdflatex lxmldoc.tex)
@pdfopt doc/pdf/lxmldoc.pdf doc/pdf/lxmldoc-${LXMLVERSION}.pdf @pdfopt doc/pdf/lxmldoc.pdf doc/pdf/lxmldoc-${LXMLVERSION}.pdf
Expand Down
106 changes: 85 additions & 21 deletions doc/mklatex.py
Expand Up @@ -5,23 +5,41 @@
from docstructure import SITE_STRUCTURE, HREF_MAP, BASENAME_MAP from docstructure import SITE_STRUCTURE, HREF_MAP, BASENAME_MAP
import os, shutil, re, sys import os, shutil, re, sys


try:
set
except NameError:
# Python 2.3
from sets import Set as set

TARGET_FILE = "lxmldoc.tex" TARGET_FILE = "lxmldoc.tex"


RST2LATEX_OPTIONS = " ".join([ RST2LATEX_OPTIONS = " ".join([
# "--no-toc-backlinks", # "--no-toc-backlinks",
"--strip-comments", "--strip-comments",
"--language en", "--language en",
# "--date", "--date",
"--use-latex-footnotes", "--use-latex-footnotes",
"--use-latex-citations", "--use-latex-citations",
"--use-latex-toc", "--use-latex-toc",
#"--font-encoding=T1", "--font-encoding=T1",
"--output-encoding=utf-8",
"--input-encoding=utf-8",
]) ])


htmlnsmap = {"h" : "http://www.w3.org/1999/xhtml"} htmlnsmap = {"h" : "http://www.w3.org/1999/xhtml"}


replace_invalid = re.compile(r'[-_/.\s\\]').sub replace_invalid = re.compile(r'[-_/.\s\\]').sub


replace_epydoc_macros = re.compile(r'(,\s*amssymb|dvips\s*,\s*)').sub
replace_rst_macros = re.compile(r'(\\usepackage\{color}|\\usepackage\[[^]]*]\{hyperref})').sub

FILENAME_MAP = {
"@API reference" : "api.tex"
}

BASENAME_MAP = BASENAME_MAP.copy()
BASENAME_MAP.update({'api' : 'lxmlapi'})

# LaTeX snippets # LaTeX snippets


DOCUMENT_CLASS = r""" DOCUMENT_CLASS = r"""
Expand All @@ -36,12 +54,18 @@
\input{_part_pygments.tex} \input{_part_pygments.tex}
""" """


def write_chapter(master, title, outname): EPYDOC_IMPORT = r"""
\input{_part_epydoc.tex}
"""

def write_chapter(master, title, filename):
filename = os.path.join(os.path.dirname(filename),
"_part_%s" % os.path.basename(filename))
master.write(r""" master.write(r"""
\chapter{%s} \chapter{%s}
\label{_part_%s} \label{%s}
\input{_part_%s} \input{%s}
""".replace(' ', '') % (title, outname, outname)) """.replace(' ', '') % (title, filename, filename))




# the program ---- # the program ----
Expand All @@ -57,8 +81,25 @@ def build_pygments_macros(filename):
text = LatexFormatter().get_style_defs() text = LatexFormatter().get_style_defs()
f = file(filename, "w") f = file(filename, "w")
f.write(text) f.write(text)
f.write('\n')
f.close() f.close()


def copy_epydoc_macros(src, dest, existing_header_lines):
doc = file(src, 'r')
out = file(dest, "w")
for line in doc:
if line.startswith('%% generator'):
break
if line.startswith('%') or \
r'\documentclass' in line or \
r'\makeindex' in line:
continue
if line.startswith(r'\usepackage') and line in existing_header_lines:
continue
out.write( replace_epydoc_macros('', line) )
out.close()
doc.close()

def noop(input): def noop(input):
return input return input


Expand All @@ -79,6 +120,7 @@ def tex_postprocess(src, dest, want_header = False, process_line=noop):
""" """
title = '' title = ''
header = [] header = []
add_header_line = header.append
global counter_no global counter_no
counter_no = counter_no + 1 counter_no = counter_no + 1
counter_text = "listcnt%d" % counter_no counter_text = "listcnt%d" % counter_no
Expand All @@ -92,8 +134,10 @@ def tex_postprocess(src, dest, want_header = False, process_line=noop):
iter_lines = iter(src.readlines()) iter_lines = iter(src.readlines())
for l in iter_lines: for l in iter_lines:
l = process_line(l) l = process_line(l)
if not l:
continue
if want_header: if want_header:
header.append(l) add_header_line(replace_rst_macros('', l))
m = search_title(l) m = search_title(l)
if m: if m:
title = m.group(0) title = m.group(0)
Expand Down Expand Up @@ -131,6 +175,7 @@ def publish(dirname, lxml_path, release):


# build pygments macros # build pygments macros
build_pygments_macros(os.path.join(dirname, '_part_pygments.tex')) build_pygments_macros(os.path.join(dirname, '_part_pygments.tex'))
have_epydoc_macros = False


# Used in postprocessing of generated LaTeX files # Used in postprocessing of generated LaTeX files
header = [] header = []
Expand Down Expand Up @@ -160,28 +205,43 @@ def fix_relative_hyperrefs(line):
# Building pages # Building pages
for section, text_files in SITE_STRUCTURE: for section, text_files in SITE_STRUCTURE:
for filename in text_files: for filename in text_files:
if filename.startswith('@'): special = False
if filename in FILENAME_MAP:
outname = FILENAME_MAP[filename]
if not have_epydoc_macros:
have_epydoc_macros = True
copy_epydoc_macros(
os.path.join(dirname, outname),
os.path.join(dirname, '_part_epydoc.tex'),
set(header))
special = True
elif filename.startswith('@'):
print "Not yet implemented: %s" % filename[1:] print "Not yet implemented: %s" % filename[1:]
continue
#page_title = filename[1:] #page_title = filename[1:]
#url = href_map[page_title] #url = href_map[page_title]
#build_menu_entry(page_title, url, section_head) #build_menu_entry(page_title, url, section_head)
else: else:
path = os.path.join(doc_dir, filename)
basename = os.path.splitext(os.path.basename(filename))[0] basename = os.path.splitext(os.path.basename(filename))[0]
basename = BASENAME_MAP.get(basename, basename) basename = BASENAME_MAP.get(basename, basename)
outname = basename + '.tex' outname = basename + '.tex'
outpath = os.path.join(dirname, outname)
outpath = os.path.join(dirname, outname)
print "Creating %s" % outname


print "Creating %s" % outname if not special:
path = os.path.join(doc_dir, filename)
rest2latex(script, path, outpath) rest2latex(script, path, outpath)


final_name = os.path.join(dirname, "_part_%s" % outname) final_name = os.path.join(dirname, os.path.dirname(outname),
"_part_%s" % os.path.basename(outname))


title, hd = tex_postprocess(outpath, final_name, not header, title, hd = tex_postprocess(outpath, final_name,
process_line=fix_relative_hyperrefs) want_header = not header,
if not header: process_line=fix_relative_hyperrefs)
header = hd if not header:
titles[outname] = title header = hd
titles[outname] = title


# also convert CHANGES.txt # also convert CHANGES.txt
find_version_title = re.compile( find_version_title = re.compile(
Expand Down Expand Up @@ -209,8 +269,10 @@ def fix_changelog(line):
if hln.startswith(r"\documentclass"): if hln.startswith(r"\documentclass"):
#hln = hln.replace('article', 'book') #hln = hln.replace('article', 'book')
hln = DOCUMENT_CLASS hln = DOCUMENT_CLASS
elif hln.startswith("%% generator "):
master.write(EPYDOC_IMPORT)
elif hln.startswith(r"\begin{document}"): elif hln.startswith(r"\begin{document}"):
# pygments support # pygments and epydoc support
master.write(PYGMENTS_IMPORT) master.write(PYGMENTS_IMPORT)
elif hln.startswith(r"\title{"): elif hln.startswith(r"\title{"):
hln = re.sub("\{[^\}]*\}", hln = re.sub("\{[^\}]*\}",
Expand All @@ -224,8 +286,10 @@ def fix_changelog(line):
for section, text_files in SITE_STRUCTURE: for section, text_files in SITE_STRUCTURE:
master.write("\n\n\\part{%s}\n" % section) master.write("\n\n\\part{%s}\n" % section)
for filename in text_files: for filename in text_files:
if filename.startswith('@'): if filename in FILENAME_MAP:
pass outname = FILENAME_MAP[filename]
elif filename.startswith('@'):
continue
#print "Not yet implemented: %s" % filename[1:] #print "Not yet implemented: %s" % filename[1:]
#page_title = filename[1:] #page_title = filename[1:]
#url = href_map[page_title] #url = href_map[page_title]
Expand All @@ -234,7 +298,7 @@ def fix_changelog(line):
basename = os.path.splitext(os.path.basename(filename))[0] basename = os.path.splitext(os.path.basename(filename))[0]
basename = BASENAME_MAP.get(basename, basename) basename = BASENAME_MAP.get(basename, basename)
outname = basename + '.tex' outname = basename + '.tex'
write_chapter(master, titles[outname], outname) write_chapter(master, titles[outname], outname)


write_chapter(master, "Changes", chgname) write_chapter(master, "Changes", chgname)


Expand Down

0 comments on commit d309884

Please sign in to comment.