From ba28bdb0cc6cec6abcac6d4854a3d7ecebc1392c Mon Sep 17 00:00:00 2001
From: Dominik Gresch <greschd@gmx.ch>
Date: Tue, 12 Jun 2018 14:24:55 +0200
Subject: [PATCH] Fix sphinxext command by allowing whitespace in argument

Previously, this command used a fixed number of 'optional' arguments,
which contained the signature of the WorkChain split by whitespace.
By allowing whitespace in the argument, it can be passed as a single
argument, making the directive stable w.r.t. adding / removing arguments
in the workchain __init__.
---
 .gitignore                                         |  1 +
 aiida/sphinxext/tests/Makefile                     |  4 ++--
 .../tests/reference_results/workchain.xml          | 14 ++++++++++++--
 aiida/sphinxext/workchain.py                       |  5 ++++-
 4 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/.gitignore b/.gitignore
index 2366d42a13..1cb7db3675 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,6 +19,7 @@
 *\,cover
 coverage/
 .cache
+.pytest_cache
 .coverage
 
 # Files created by RPN tests
diff --git a/aiida/sphinxext/tests/Makefile b/aiida/sphinxext/tests/Makefile
index d044c9266a..926a7fb24d 100644
--- a/aiida/sphinxext/tests/Makefile
+++ b/aiida/sphinxext/tests/Makefile
@@ -23,8 +23,8 @@ I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)
 all: html
 
 clean:
-	rm -r $(BUILDDIR)
-	rm -r $(HTMLBUILDDIR)
+	@rm -r $(BUILDDIR) || true
+	@rm -r $(HTMLBUILDDIR) || true
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(HTMLBUILDDIR)
diff --git a/aiida/sphinxext/tests/reference_results/workchain.xml b/aiida/sphinxext/tests/reference_results/workchain.xml
index 28438a25e2..862f9809c1 100644
--- a/aiida/sphinxext/tests/reference_results/workchain.xml
+++ b/aiida/sphinxext/tests/reference_results/workchain.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE document PUBLIC "+//IDN docutils.sourceforge.net//DTD Docutils Generic//EN//XML" "http://docutils.sourceforge.net/docs/ref/docutils.dtd">
-<!-- Generated by Docutils 0.13.1 -->
-<document source="/home/martin/src/aiida_core/aiida/sphinxext/tests/workchain_source/index.rst">
+<!-- Generated by Docutils 0.14 -->
+<document source="/home/greschd/programming/aiida/aiida_core/aiida/sphinxext/tests/workchain_source/index.rst">
     <section ids="sphinx-aiida-demo" names="sphinx-aiida\ demo">
         <title>sphinx-aiida demo</title>
         <paragraph>This is a demo documentation to show off the features of the <literal>sphinx-aiida</literal> extension.</paragraph>
@@ -32,6 +32,16 @@
         <target ids="module-demo_workchain" ismod="True"></target>
         <index entries="['single',\ u'demo_workchain\ (module)',\ u'module-demo_workchain',\ '',\ None]"></index>
         <paragraph>This module defines an example workchain for the aiida-workchain documentation directive.</paragraph>
+        <desc desctype="class" domain="py" noindex="False" objtype="class">
+            <desc_signature first="False" fullname="Workchain"><desc_annotation xml:space="preserve">workchain</desc_annotation><desc_addname xml:space="preserve">demo_workchain.</desc_addname><desc_name xml:space="preserve">DemoWorkChain</desc_name></desc_signature>
+            <desc_content>
+                <paragraph>
+                        A demo workchain to show how the workchain auto-documentation works.
+                        </paragraph>
+                <paragraph><strong>Inputs:</strong><bullet_list bullet="*"><list_item><paragraph><literal_strong>description</literal_strong>, <emphasis>basestring</emphasis>, optional, <emphasis>non_db</emphasis></paragraph></list_item><list_item><paragraph><literal_strong>label</literal_strong>, <emphasis>basestring</emphasis>, optional, <emphasis>non_db</emphasis></paragraph></list_item><list_item><literal_strong>nsp</literal_strong>, <emphasis>Namespace</emphasis> – A separate namespace, <literal>nsp</literal>.<bullet_list bullet="*"></bullet_list></list_item><list_item><literal_strong>nsp2</literal_strong>, <emphasis>Namespace</emphasis><bullet_list bullet="*"></bullet_list></list_item><list_item><paragraph><literal_strong>store_provenance</literal_strong>, <emphasis>bool</emphasis>, optional, <emphasis>non_db</emphasis></paragraph></list_item><list_item><paragraph><literal_strong>x</literal_strong>, <emphasis>Float</emphasis>, required – First input argument.</paragraph></list_item><list_item><literal_strong>y</literal_strong>, <emphasis>Namespace</emphasis><bullet_list bullet="*"><list_item><paragraph><literal_strong>z</literal_strong>, <emphasis>Int</emphasis>, required – Input in a separate namespace.</paragraph></list_item></bullet_list></list_item></bullet_list></paragraph>
+                <paragraph><strong>Outputs:</strong><bullet_list bullet="*"><list_item><paragraph><literal_strong>z</literal_strong>, <emphasis>Bool</emphasis>, required – Output of the demoworkchain.</paragraph></list_item></bullet_list></paragraph>
+            </desc_content>
+        </desc>
         <index entries="['single',\ u'NormalClass\ (class\ in\ demo_workchain)',\ u'demo_workchain.NormalClass',\ '',\ None]"></index>
         <desc desctype="class" domain="py" noindex="False" objtype="class">
             <desc_signature class="" first="False" fullname="NormalClass" ids="demo_workchain.NormalClass" module="demo_workchain" names="demo_workchain.NormalClass"><desc_annotation xml:space="preserve">class </desc_annotation><desc_addname xml:space="preserve">demo_workchain.</desc_addname><desc_name xml:space="preserve">NormalClass</desc_name></desc_signature>
diff --git a/aiida/sphinxext/workchain.py b/aiida/sphinxext/workchain.py
index 20bb69c4cf..0c952394c4 100644
--- a/aiida/sphinxext/workchain.py
+++ b/aiida/sphinxext/workchain.py
@@ -39,9 +39,12 @@ class AiidaWorkchainDirective(Directive):
     Directive to auto-document AiiDA workchains.
     """
     required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+
     HIDE_UNSTORED_INPUTS_FLAG = 'hide-nondb-inputs'
-    optional_arguments = 2
     option_spec = {'module': directives.unchanged, HIDE_UNSTORED_INPUTS_FLAG: directives.flag}
+
     has_content = True
 
     def run(self):