From f26aa317f4fc4900d9870a47d7181a8bc46f93cf Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Tue, 26 May 2009 08:58:10 -0400 Subject: Finally looks like I'll be able to write .px files directly. --- doc/Makefile | 5 +++++ doc/_ext/px_xlator.py | 61 +++++++++++++++++++++++++++++++++++++++++++++------ doc/cmd.rst | 8 +++---- doc/conf.py | 3 +-- doc/index.rst | 20 +++++++++++------ 5 files changed, 77 insertions(+), 20 deletions(-) (limited to 'doc') diff --git a/doc/Makefile b/doc/Makefile index da5df57..5be97aa 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -30,6 +30,11 @@ html: @echo @echo "Build finished. The HTML pages are in _build/html." +px: + $(SPHINXBUILD) -b px $(ALLSPHINXOPTS) _build/px + @echo + @echo "Build finished. The HTML pages are in _build/px." + text: $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) _build/text @echo diff --git a/doc/_ext/px_xlator.py b/doc/_ext/px_xlator.py index 5314f42..65cb761 100644 --- a/doc/_ext/px_xlator.py +++ b/doc/_ext/px_xlator.py @@ -1,18 +1,65 @@ +from docutils import nodes from sphinx.writers.html import SmartyPantsHTMLTranslator from sphinx.builders.html import StandaloneHTMLBuilder +def setup(app): + app.add_builder(PxBuilder) + + class PxTranslator(SmartyPantsHTMLTranslator): """Adjust the HTML translator into a .px translator. """ + def __init__(self, *args, **kwargs): + SmartyPantsHTMLTranslator.__init__(self, *args, **kwargs) + #self.document.reporter.debug_flag = 1 + def visit_section(self, node): - self.body.append("") - SmartyPantsHTMLTranslator.visit_section(self, node) - self.body.append("") + self.section_level += 1 + + def depart_section(self, node): + self.section_level -= 1 + + + # TODO: get history from here? + def visit_field_list(self, node): + #self.document.reporter.debug_flag = 1; # This should go somewhere else. + raise nodes.SkipNode + def depart_field_list(self, node): pass + def visit_field(self, node): pass + def depart_field(self, node): pass + def visit_field_name(self, node): pass + def depart_field_name(self, node): pass + def visit_field_body(self, node): pass + def depart_field_body(self, node): pass + + def xx_visit_Text(self, node): + self.body.append("XX") + SmartyPantsHTMLTranslator.visit_Text(self, node) + + def visit_literal_block(self, node): + if node.rawsource != node.astext(): + # most probably a parsed-literal block -- don't highlight + return BaseTranslator.visit_literal_block(self, node) + lang = self.highlightlang + if node.has_key('language'): + # code-block directives + lang = node['language'] + self.body.append('' % lang) + self.body.append(self.encode(node.rawsource)) + self.body.append('\n') + raise nodes.SkipNode + class PxBuilder(StandaloneHTMLBuilder): - def get_target_uri(self, docname, typ=None): - import pdb;pdb.set_trace() - return docname + self.link_suffix - \ No newline at end of file + name = 'px' + + def init(self): + self.config.html_theme = 'px' + self.config.html_translator_class = "px_xlator.PxTranslator" + + super(PxBuilder, self).init() + + self.out_suffix = '.px' + self.link_suffix = '.html' diff --git a/doc/cmd.rst b/doc/cmd.rst index 5b4b7a3..bb01fd5 100644 --- a/doc/cmd.rst +++ b/doc/cmd.rst @@ -97,7 +97,7 @@ The -m flag also shows the line numbers of missing statements:: ------------------------------------------------------- TOTAL 91 79 87% -You can restrict the report to files you are interested in by naming them on the +You can restrict the report to only certain files by naming them on the command line:: $ coverage -r -m my_program.py my_other_module.py @@ -108,8 +108,8 @@ command line:: ------------------------------------------------------- TOTAL 76 66 87% -You can use the -o flag to omit files that begin with specified prefixes. -For example, this will skip reporting on any modules in the django directory:: +The -o flag omits files that begin with specified prefixes. For example, this +will omit any modules in the django directory:: $ coverage -r -m -o django @@ -118,7 +118,7 @@ For example, this will skip reporting on any modules in the django directory:: HTML Annotation --------------- -Coverage can show you your source code, annotated for which lines were executed, +Coverage can annotate your source code for which lines were executed and which were not. The -b flag creates an HTML report similar to the -r summary, but as an HTML file. Each module name links to the source file decorated to show the status of each line. diff --git a/doc/conf.py b/doc/conf.py index 64e145b..2044bf8 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -24,7 +24,7 @@ sys.path.append(os.path.join(os.path.dirname(__file__), "_ext")) # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'px_xlator'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -88,7 +88,6 @@ pygments_style = 'sphinx' # A list of ignored prefixes for module index sorting. #modindex_common_prefix = [] - # -- Options for HTML output --------------------------------------------------- #html_translator_class = "px_xlator.PxTranslator" diff --git a/doc/index.rst b/doc/index.rst index 3d68da5..d28e7a7 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -31,15 +31,14 @@ Quick Start Getting started with coverage.py is easy: -#. Install coverage.py from the `coverage page on the cheeseshop `_. +#. Install coverage.py from the + `coverage page on the cheeseshop `_. #. Run coverage.py to execute your program and gather data:: $ coverage -e -x my_program.py arg1 arg2 blah blah ..your program's output.. blah blah - "-e -x" means erase coverage data from previous runs and execute a program. - #. Run coverage.py to report on the results:: $ coverage -r -m @@ -50,14 +49,21 @@ Getting started with coverage.py is easy: ------------------------------------------------------- TOTAL 76 66 87% - "-r -m" means show a summary report and include the missing line numbers. - #. For a nicer presentation, run coverage.py to get annotated HTML listings detailing missed lines:: - coverage -b -d htmlcov + $ coverage -b -i -d htmlcov + + Then visit htmlcov/index.html in your browser, to see a + `report like this `_. + +Getting Help +~~~~~~~~~~~~ + +This is a third-level section, with some XML:: - Then visit htmlcov/index.html in your browser. + 1 < 2 & 2 > 1 + Whoa! Using coverage.py -- cgit v1.2.1