Patchwork [3,of,4] doc: add some doctests to gendoc.py to check option printing

login
register
mail settings
Submitter Simon Heimberg
Date Feb. 20, 2014, 5:04 p.m.
Message ID <8e19fd0d5ec2a8dc9c36.1392915883@lapsi.heimberg.home>
Download mbox | patch
Permalink /patch/3724/
State Accepted
Headers show

Comments

Simon Heimberg - Feb. 20, 2014, 5:04 p.m.
# HG changeset patch
# User simon@laptop-tosh
# Date 1392909203 -3600
#      Thu Feb 20 16:13:23 2014 +0100
# Node ID 8e19fd0d5ec2a8dc9c361bcecab020fa400a1256
# Parent  9f1794bed2db8a443e175de16871dab4ef8dda2b
doc: add some doctests to gendoc.py to check option printing
Simon Heimberg - March 6, 2014, 5:58 a.m.
On 20.02.2014 18:04, Simon Heimberg wrote:
> # HG changeset patch
> # User simon@laptop-tosh
> # Date 1392909203 -3600
> #      Thu Feb 20 16:13:23 2014 +0100
> # Node ID 8e19fd0d5ec2a8dc9c361bcecab020fa400a1256
> # Parent  9f1794bed2db8a443e175de16871dab4ef8dda2b
> doc: add some doctests to gendoc.py to check option printing

Any feedback to the patches in this series?
(Patch 4 is optional, therefore replying to 3)

>
> diff -r 9f1794bed2db -r 8e19fd0d5ec2 doc/gendoc.py
> --- a/doc/gendoc.py	Thu Feb 20 09:17:22 2014 +0100
> +++ b/doc/gendoc.py	Thu Feb 20 16:13:23 2014 +0100
> @@ -76,7 +76,26 @@
>
>       return d
>
> -def showdoc(ui):
> +def showdoc(ui, globalopts=globalopts, table=table, helptable=helptable,
> +            extensionnames=None):
<snip>
Matt Mackall - March 6, 2014, 10:17 p.m.
On Thu, 2014-02-20 at 18:04 +0100, Simon Heimberg wrote:
> # HG changeset patch
> # User simon@laptop-tosh
> # Date 1392909203 -3600
> #      Thu Feb 20 16:13:23 2014 +0100
> # Node ID 8e19fd0d5ec2a8dc9c361bcecab020fa400a1256
> # Parent  9f1794bed2db8a443e175de16871dab4ef8dda2b
> doc: add some doctests to gendoc.py to check option printing

I've queued the first two, check-code complains about a hard-to-fix long
line in this one though. Also:

> -def showdoc(ui):
> +def showdoc(ui, globalopts=globalopts, table=table, helptable=helptable,
> +            extensionnames=None):

Doctests are best when we don't have to mock up a bunch of
input/environment to make the function happy. Perhaps it would be better
to factor out a _helperfunction that could have more encapsulated
tests?

Patch

diff -r 9f1794bed2db -r 8e19fd0d5ec2 doc/gendoc.py
--- a/doc/gendoc.py	Thu Feb 20 09:17:22 2014 +0100
+++ b/doc/gendoc.py	Thu Feb 20 16:13:23 2014 +0100
@@ -76,7 +76,26 @@ 
 
     return d
 
-def showdoc(ui):
+def showdoc(ui, globalopts=globalopts, table=table, helptable=helptable,
+            extensionnames=None):
+    """write the documentation for hg.1 to ui
+
+    test printing of global options:
+    >>> opts = [('e', 'example', '', 'desc for e'),
+    ...         ('s', 'some', True, 'a description\\non several lines')]
+    >>> showdoc(sys.stdout, opts, {}, {}, lambda: []) # doctest: +ELLIPSIS
+    Options
+    ""\"""\""
+    <BLANKLINE>
+    -e, --example <VALUE>
+        desc for e
+    <BLANKLINE>
+    -s, --some
+        a description on several lines (default: True)
+    <BLANKLINE>
+    Commands
+    ...
+    """
     # print options
     ui.write(minirst.section(_("Options")))
     multioccur = False
@@ -106,7 +125,9 @@ 
              "   :local:\n"
              "   :depth: 1\n\n")
 
-    for extensionname in sorted(allextensionnames()):
+    if extensionnames is None:
+        extensionnames = allextensionnames
+    for extensionname in sorted(extensionnames()):
         mod = extensions.load(None, extensionname, None)
         ui.write(minirst.subsection(extensionname))
         ui.write("%s\n\n" % gettext(mod.__doc__))
@@ -143,6 +164,28 @@ 
         ui.write("\n")
 
 def commandprinter(ui, cmdtable, sectionfunc):
+    """write documentation about the commands from cmdtable to ui
+
+    test option printing
+    >>> def t():
+    ...     "desc of test"
+    >>> table = {'test': (t, [('o', 'opt', 3, 'this is a long description\\n'
+    ...                                       'with several lines'),
+    ...                       ('', 'p', None, 'desc for p')], '[OPTS]')}
+    >>> commandprinter(sys.stdout, table, lambda c: None)
+    ::
+    <BLANKLINE>
+       hg test [OPTS]
+    <BLANKLINE>
+    desc of test
+    <BLANKLINE>
+    Options:
+    <BLANKLINE>
+    -o, --opt <VALUE>  this is a long description with several lines (default: 3)
+    --p                desc for p
+    <BLANKLINE>
+    """
+
     h = {}
     for c, attr in cmdtable.items():
         f = c.split("|")[0]
@@ -199,5 +242,16 @@ 
 
     if doc == 'hg.1.gendoc':
         showdoc(sys.stdout)
+    elif doc == '--doctest':
+        if 'TERM' in os.environ:
+            del os.environ['TERM']
+        import doctest
+        failures, tests = doctest.testmod()
+        if failures:
+            from mercurial import i18n
+            lang = i18n.t.info().get('language')
+            if lang not in (None, 'en'):
+                print '  maybe failed because language is', lang
+        sys.exit(failures and 1 or 0)
     else:
         showtopic(sys.stdout, sys.argv[1])
diff -r 9f1794bed2db -r 8e19fd0d5ec2 tests/test-gendoc.t
--- a/tests/test-gendoc.t	Thu Feb 20 09:17:22 2014 +0100
+++ b/tests/test-gendoc.t	Thu Feb 20 16:13:23 2014 +0100
@@ -3,6 +3,9 @@ 
   $ "$TESTDIR/hghave" docutils || exit 80
   $ HGENCODING=UTF-8
   $ export HGENCODING
+
+  $ python "$TESTDIR/../doc/gendoc.py" --doctest
+
   $ { echo C; ls "$TESTDIR/../i18n"/*.po | sort; } | while read PO; do
   >     LOCALE=`basename "$PO" .po`
   >     echo