[GRASS-SVN] r72749 - sandbox/wenzeslaus/g.citation

[svn_grass at osgeo.org]

Author: wenzeslaus
Date: 2018-05-28 14:42:31 -0700 (Mon, 28 May 2018)
New Revision: 72749

Modified:
   sandbox/wenzeslaus/g.citation/g.citation.py
Log:
g.citation: doctest and doc

Modified: sandbox/wenzeslaus/g.citation/g.citation.py
===================================================================
--- sandbox/wenzeslaus/g.citation/g.citation.py	2018-05-28 20:54:40 UTC (rev 72748)
+++ sandbox/wenzeslaus/g.citation/g.citation.py	2018-05-28 21:42:31 UTC (rev 72749)
@@ -62,6 +62,7 @@
 
 from __future__ import print_function
 
+import sys
 import os
 import re
 
@@ -91,6 +92,11 @@
 
 
 def remove_non_author_lines(lines):
+    """Remove lines which appear in the authors sec but are not authors
+
+    >>> remove_non_author_lines(["Ann Doe", "© 2012", "John Doe"])
+    ['Ann Doe', 'John Doe']
+    """
     out = []
     for line in lines:
         if "©" in line:
@@ -110,6 +116,11 @@
 
 
 def clean_line_item(text):
+    """Clean (commas and spaces) from beginning and end of a text
+
+    >>> print(clean_line_item(",Small University, "))
+    Small University
+    """
     text = text.strip()
     text = re.sub(r"^, *", "", text)
     text = re.sub(r",$", "", text)
@@ -117,13 +128,28 @@
 
 
 def get_year_from_documentation(text):
+    """Extract year from text containing SVN date entry
+
+    >>> text = "<p><i>Last changed: $Date: 2011-09-29 15:18:47 $</i>"
+    >>> get_year_from_documentation(text)
+    2011
+    """
     year_capture = r"<p>\s*<i>Last changed: \$Date: ([\d]+)-\d\d-\d\d .*\$</i>"
     match = re.search(year_capture, text,
                       re.MULTILINE | re.DOTALL)
     if match:
         return int(match.group(1))
+    else:
+        # TODO: raise or fatal? should be in library or module?
+        raise RuntimeError("The text does not contain date entry")
 
 def get_authors_from_documentation(text):
+    r"""Extract authors and associated info from documentation
+
+    >>> text = '<h2><a name="author">AUTHOR</a></h2>\nPaul Kelly\n<p><i>Last changed:'
+    >>> pprint(get_authors_from_documentation(text))
+    [{'feature': None, 'institute': None, 'name': 'Paul Kelly', 'orcid': None}]
+    """
     raw_author_capture = "<h2>.*AUTHOR.*</h2>(.*)<p>\s*<i>Last changed:"
 
     raw_author_lines = [
@@ -161,18 +187,33 @@
 
 
 def print_bibtex(citation):
+    """Create BibTeX entry from citation dictionary
+
+    >>> print_bibtex({'module': 'g.tst', 'authors': [{'name': 'Joe Doe'}], 'year': 2011})
+    @software{g.tst,
+      title = {GRASS GIS: g.tst module},
+      author = {Joe Doe},
+      year = {2011}
+    }
+    """
     print("@software{", citation['module'], ",", sep="")
 
-    print("title={", "GRASS GIS: ", citation['module'], " module},", sep="")
+    print("  title = {", "GRASS GIS: ", citation['module'], " module},", sep="")
 
     author_names = [author['name'] for author in citation['authors']]
-    print("author={", " and ".join(author_names), "},", sep="")
-    print("year={", citation['year'], "},", sep="")
+    print("  author = {", " and ".join(author_names), "},", sep="")
+    print("  year = {", citation['year'], "}", sep="")
 
     print("}")
 
 
 def print_plain(citation):
+    """Create citation from dictionary as plain text
+
+    >>> print_plain({'module': 'g.tst', 'authors': [{'name': 'Joe Doe'}]})
+    GRASSS GIS module g.tst
+    Joe Doe
+    """
     print("GRASSS GIS module", citation['module'])
     num_authors = len(citation['authors'])
     authors_text = ""
@@ -179,9 +220,11 @@
     for i, author in enumerate(citation['authors']):
         author_name = [ ]
         authors_text += author['name']
-        if author['institute']:
+        # TODO: not defined if we need institute etc. or not, perhaps
+        # use default dict
+        if 'institute' in author and author['institute']:
             authors_text += ", {institute}".format(**author)
-        if author['feature']:
+        if 'feature' in author and author['feature']:
             authors_text += " ({feature})".format(**author)
         if i < num_authors - 1:
             authors_text += "\n"
@@ -188,12 +231,13 @@
     print(authors_text)
 
 
-def print_citation(citation, output_format):
-    if output_format == 'bibtex':
+def print_citation(citation, format):
+    """Create citation from dictionary in a given format"""
+    if format == 'bibtex':
         print_bibtex(citation)
-    elif output_format == 'plain':
+    elif format == 'plain':
         print_plain(citation)
-    elif output_format == 'dict':
+    elif format == 'dict':
         pprint(citation)
     else:
         raise RuntimeError(_("Unsupported format or style"))
@@ -200,6 +244,7 @@
 
 
 def citation_for_module(name):
+    """Provide dictionary of citation values for a module"""
     path = documentation_filename(name)
 
     # derive core strings from lhmpom:
@@ -216,7 +261,12 @@
 
 
 def main(options, flags):
+    """Main function to do the module's work
 
+    Using minimal design, just getting the input and calling other
+    functions.
+    """
+
     name = options['module']
     output_format = options['format']
 
@@ -242,5 +292,19 @@
 #  url = {http://grass.osgeo.org},
 # }
 
+
+def doc_test():
+    """Tests the module using doctest
+
+    :return: a number of failed tests
+    """
+    import doctest
+    from grass.gunittest.utils import do_doctest_gettext_workaround
+    do_doctest_gettext_workaround()
+    return doctest.testmod().failed
+
+
 if __name__ == '__main__':
-    main(*gs.parser())
+    if '--doctest' in sys.argv:
+        sys.exit(doc_test())
+    sys.exit(main(*gs.parser()))