From e93f40cd1cb9d49464b2a60fa0287e806892456c Mon Sep 17 00:00:00 2001
From: Ben Nemec <bnemec@redhat.com>
Date: Mon, 30 Apr 2018 16:23:37 +0000
Subject: [PATCH] Fix doc build

Most notably, taskflow is hitting the sphinx issue
https://github.com/sphinx-doc/sphinx/issues/2549 which causes a
spurious warning that breaks the build with -W.  There is a
workaround posted in
https://stackoverflow.com/questions/31784830/sphinx-ivar-tag-goes-looking-for-cross-references
to move :ivar: docstrings to inline comments on the member variable
itself.  This is not ideal because it causes the docs to render
differently from :ivar:, but until the sphinx bug is fixed it will
allow us to keep documenting the problematic variables.

There was also a problem with one of the doctests because the
output had changed.  That is now fixed.

I also noticed a typo in one of the parameter descriptions so that
is fixed too.

Change-Id: Ib44621f6c3ba2c5476ec430218a0449f9f45d18f
---
 doc/source/user/inputs_and_outputs.rst | 6 +++---
 taskflow/atom.py                       | 8 +++++---
 taskflow/persistence/models.py         | 8 ++++++--
 3 files changed, 14 insertions(+), 8 deletions(-)

diff --git a/doc/source/user/inputs_and_outputs.rst b/doc/source/user/inputs_and_outputs.rst
index 27691da19..d0b5b7ef9 100644
--- a/doc/source/user/inputs_and_outputs.rst
+++ b/doc/source/user/inputs_and_outputs.rst
@@ -99,9 +99,9 @@ prior to running:
    >>> engines.run(flo)
    Traceback (most recent call last):
       ...
-   taskflow.exceptions.MissingDependencies:
-   taskflow.patterns.linear_flow.Flow: cat-dog;
-   2 requires ['meow', 'woof'] but no other entity produces said requirements
+   taskflow.exceptions.MissingDependencies: 'linear_flow.Flow: cat-dog(len=2)' requires ['meow', 'woof'] but no other entity produces said requirements
+    MissingDependencies: 'execute' method on '__main__.DogTalk==1.0' requires ['woof'] but no other entity produces said requirements
+    MissingDependencies: 'execute' method on '__main__.CatTalk==1.0' requires ['meow'] but no other entity produces said requirements
 
 The recommended way to provide flow inputs is to use the ``store`` parameter
 of the engine helpers (:py:func:`~taskflow.engines.helpers.run` or
diff --git a/taskflow/atom.py b/taskflow/atom.py
index 8dcc6dc82..f35624752 100644
--- a/taskflow/atom.py
+++ b/taskflow/atom.py
@@ -189,7 +189,7 @@ class Atom(object):
     :param requires: A set or list of required inputs for this atom's
                      ``execute`` method.
     :param revert_requires: A set or list of required inputs for this atom's
-                            ``revert`` method. If unpassed, ```requires`` will
+                            ``revert`` method. If unpassed, ``requires`` will
                             be used.
     :ivar version: An *immutable* version that associates version information
                    with this atom. It can be useful in resuming older versions
@@ -212,8 +212,6 @@ class Atom(object):
                          a different ``revert_rebind`` value was received.
     :ivar inject: See parameter ``inject``.
     :ivar Atom.name: See parameter ``name``.
-    :ivar requires: A :py:class:`~taskflow.types.sets.OrderedSet` of inputs
-                    this atom requires to function.
     :ivar optional: A :py:class:`~taskflow.types.sets.OrderedSet` of inputs
                     that are optional for this atom to ``execute``.
     :ivar revert_optional: The ``revert`` version of ``optional``.
@@ -284,6 +282,10 @@ class Atom(object):
         (self.revert_rebind, addl_requires,
          self.revert_optional) = revert_mapping
 
+        # TODO(bnemec): This should be documented as an ivar, but can't be due
+        # to https://github.com/sphinx-doc/sphinx/issues/2549
+        #: A :py:class:`~taskflow.types.sets.OrderedSet` of inputs this atom
+        #: requires to function.
         self.requires = exec_requires.union(addl_requires)
 
     def _build_arg_mapping(self, executor, requires=None, rebind=None,
diff --git a/taskflow/persistence/models.py b/taskflow/persistence/models.py
index 310624017..0c3385a80 100644
--- a/taskflow/persistence/models.py
+++ b/taskflow/persistence/models.py
@@ -301,13 +301,15 @@ class FlowDetail(object):
     guaranteed to be persisted when a save (or update) occurs via some backend
     connection.
 
-    :ivar state: The state of the flow associated with this flow detail.
     :ivar meta: A dictionary of meta-data associated with this flow detail.
     """
     def __init__(self, name, uuid):
         self._uuid = uuid
         self._name = name
         self._atomdetails_by_id = {}
+        # TODO(bnemec): This should be documented as an ivar, but can't be due
+        # to https://github.com/sphinx-doc/sphinx/issues/2549
+        #: The state of the flow associated with this flow detail.
         self.state = None
         self.meta = {}
 
@@ -486,7 +488,6 @@ class AtomDetail(object):
     guaranteed to be persisted when a save (or update) occurs via some backend
     connection.
 
-    :ivar state: The state of the atom associated with this atom detail.
     :ivar intention: The execution strategy of the atom associated
                      with this atom detail (used by an engine/others to
                      determine if the associated atom needs to be
@@ -515,6 +516,9 @@ class AtomDetail(object):
     def __init__(self, name, uuid):
         self._uuid = uuid
         self._name = name
+        # TODO(bnemec): This should be documented as an ivar, but can't be due
+        # to https://github.com/sphinx-doc/sphinx/issues/2549
+        #: The state of the atom associated with this atom detail.
         self.state = None
         self.intention = states.EXECUTE
         self.results = None