Merge branch 'master' into develop

Author: dpryan79

.travis.yml

@@ -11,4 +11,4 @@ install:
 
 script:
  - py.test
- - flake8 . --ignore=E501 --exclude=docs/conf.py
+ - flake8 . --ignore=E501,E722,E741 --exclude=docs/conf.py

docs/changelog.rst

@@ -2,6 +2,11 @@
 Change log
 **********
 
+0.2.2
+#####
+
+ * CommonMark is now only imported if absolutely required. This should fix failures on read the docs. Thanks to @Chilipp for fixing this!
+
 0.2.1
 #####
 
@@ -13,7 +18,7 @@ Change log
  * Section titles can now be used in tables of contents and linked to. The title itself is also used as the anchor. In the case of repeated names `_replicateX`, where `X` is a number, is prepended to ensure that all titles are uniquely linkable. This was bug `#46 <https://github.com/ribozz/sphinx-argparse/issues/46>`_.
  * The positional (aka required) and named (aka optional) option sections are now named "Positional Arguments" and "Named Arguments", for the sake of clarity (e.g., named arguments can be required). This was issue `#58 <https://github.com/ribozz/sphinx-argparse/issues/58>`_.
  * Fixed quoting of default strings (issue `#59 <https://github.com/ribozz/sphinx-argparse/issues/59>`_).
- * Added the `:noepilogue:` and `:nodescription:` options, thanks to @arewm.
+ * Added the `:noepilog:` and `:nodescription:` options, thanks to @arewm.
  * Added the `:nosubcommand:` option, thanks to @arewm.
 
 0.1.17

docs/extend.rst

@@ -62,6 +62,9 @@ You can also add classifiers, which will change how these definitions are incorp
             --upgrade : @after
                 The after directive is the default, so you needn't specify it.
 
+       advanced arguments : @skip
+            skip advanced arguments
+
 
 @before
     Insert content before the parsed help/description message of the argument/option/subcommand/argument-group.
@@ -71,3 +74,6 @@ You can also add classifiers, which will change how these definitions are incorp
 
 @replace
     Replace content of help/description message of argument/option/subcommand/argument-group.
+
+@skip
+    Skip the content of help/description message of subcommand/argument-group.

docs/usage.rst

@@ -95,6 +95,6 @@ Other useful directives
 
 :nosubcommands: Do not show subcommands.
 
-:noepilogue: Do not parse the epilogue, which can be useful if it contains text that could be incorrectly parse as reStructuredText.
+:noepilog: Do not parse the epilogue, which can be useful if it contains text that could be incorrectly parse as reStructuredText.
 
 :nodescription: Do not parse the description, which can be useful if it contains text that could be incorrectly parse as reStructuredText.

setup.py

@@ -37,10 +37,10 @@ def getVersion():
         'Topic :: Software Development :: Documentation'
     ],
     install_requires=[
-        'sphinx>=1.2.0',
-        'CommonMark>=0.5.6'
+        'sphinx>=1.2.0'
     ],
     extras_require={
-        'dev': ['pytest', 'sphinx_rtd_theme']
+        'dev': ['pytest', 'sphinx_rtd_theme'],
+        'markdown': ['CommonMark>=0.5.6']
     }
 )

sphinxarg/__init__.py

@@ -1 +1 @@
-__version__ = '0.2.1'
+__version__ = '0.2.2'

sphinxarg/ext.py

@@ -10,7 +10,6 @@
 from sphinx.util.nodes import nested_parse_with_titles
 
 from sphinxarg.parser import parse_parser, parser_navigate
-from sphinxarg.markdown import parseMarkDownBlock
 
 
 def map_nested_definitions(nested_content):
@@ -33,7 +32,7 @@ def map_nested_definitions(nested_content):
                 if len(ci.children) > 0:
                     classifier = ci.children[0].astext()
             if classifier is not None and classifier not in (
-                    '@replace', '@before', '@after'):
+                    '@replace', '@before', '@after', '@skip'):
                 raise Exception('Unknown classifier: %s' % classifier)
             idx = subitem.first_child_matching_class(nodes.term)
             if idx is not None:
@@ -58,6 +57,7 @@ def renderList(l, markDownHelp, settings=None):
     if len(l) == 0:
         return []
     if markDownHelp:
+        from sphinxarg.markdown import parseMarkDownBlock
         return parseMarkDownBlock('\n\n'.join(l) + '\n')
     else:
         if settings is None:
@@ -93,16 +93,19 @@ def print_action_groups(data, nested_content, markDownHelp=False, settings=None)
                     desc.append(s)
                 elif classifier == '@before':
                     desc.insert(0, s)
-                for k, v in subContent.items():
-                    definitions[k] = v
+                elif classifier == '@skip':
+                    continue
+                if len(subContent) > 0:
+                    for k, v in map_nested_definitions(subContent).items():
+                        definitions[k] = v
             # Render appropriately
             for element in renderList(desc, markDownHelp):
                 section += element
 
             localDefinitions = definitions
             if len(subContent) > 0:
                 localDefinitions = {k: v for k, v in definitions.items()}
-                for k, v in map_nested_definitions(subContent):
+                for k, v in map_nested_definitions(subContent).items():
                     localDefinitions[k] = v
 
             items = []
@@ -151,7 +154,7 @@ def print_action_groups(data, nested_content, markDownHelp=False, settings=None)
     return nodes_list
 
 
-def print_subcommands(data, nested_content, markDownHelp=False):
+def print_subcommands(data, nested_content, markDownHelp=False, settings=None):
     """
     Each subcommand is a dictionary with the following keys:
 
@@ -192,12 +195,18 @@ def print_subcommands(data, nested_content, markDownHelp=False):
             for element in renderList(desc, markDownHelp):
                 sec += element
             sec += nodes.literal_block(text=child['bare_usage'])
-            for x in print_action_groups(child, nested_content + subContent, markDownHelp):
+            for x in print_action_groups(child, nested_content + subContent, markDownHelp,
+                                         settings=settings):
                 sec += x
 
-            for x in print_subcommands(child, nested_content + subContent, markDownHelp):
+            for x in print_subcommands(child, nested_content + subContent, markDownHelp,
+                                       settings=settings):
                 sec += x
 
+            if 'epilog' in child and child['epilog']:
+                for element in renderList([child['epilog']], markDownHelp):
+                    sec += element
+
             subCommands += sec
         items.append(subCommands)
 
@@ -457,6 +466,7 @@ def run(self):
         items = []
         nested_content = nodes.paragraph()
         if 'markdown' in self.options:
+            from sphinxarg.markdown import parseMarkDownBlock
             items.extend(parseMarkDownBlock('\n'.join(self.content) + '\n'))
         else:
             self.state.nested_parse(
@@ -479,7 +489,8 @@ def run(self):
         items.extend(print_action_groups(result, nested_content, markDownHelp,
                                          settings=self.state.document.settings))
         if 'nosubcommands' not in self.options:
-            items.extend(print_subcommands(result, nested_content, markDownHelp))
+            items.extend(print_subcommands(result, nested_content, markDownHelp,
+                                           settings=self.state.document.settings))
         if 'epilog' in result and 'noepilog' not in self.options:
             items.append(self._nested_parse_paragraph(result['epilog']))
 

sphinxarg/markdown.py

@@ -1,5 +1,11 @@
-from CommonMark import Parser  # >= 0.5.6
-from CommonMark.node import Node
+try:
+    from commonmark import Parser
+except ImportError:
+    from CommonMark import Parser  # >= 0.5.6
+try:
+    from commonmark.node import Node
+except ImportError:
+    from CommonMark.node import Node
 from docutils import nodes
 from docutils.utils.code_analyzer import Lexer
 

tox.ini

@@ -1,5 +1,5 @@
 [tox]
-envlist = py26,py27,py33,py34
+envlist = py26,py27,py33,py34,py35,py36
 [testenv]
-deps=pytest       # install pytest in the venvs
-commands=py.test  # or 'nosetests' or .
+deps=pytest
+commands=py.test