Autodoc fixes and tweaks (#128)

* autodoc fixes and tweaks

* black

* update release notes

doc/whats_new.rst

@@ -19,6 +19,7 @@ Bug fixes
 ~~~~~~~~~
 
 - Fix running batches of simulations using ``dask.distributed`` (:issue:`124`).
+- Fix rendering of auto-generated docstrings of process classes (:issue:`128`).
 
 v0.4.0 (7 April 2020)
 ---------------------

xsimlab/formatting.py

@@ -105,7 +105,7 @@ def var_details(var, max_line_length=70):
 
 
 def add_attribute_section(process, placeholder="{{attributes}}"):
-    data_type = "object"  # placeholder until issue #34 is solved
+    data_type = ":class:`attr.Attribute`"
 
     fmt_vars = []
 
@@ -124,7 +124,7 @@ def add_attribute_section(process, placeholder="{{attributes}}"):
     if placeholder in current_doc:
         new_doc = current_doc.replace(placeholder, fmt_section[4:])
     else:
-        new_doc = f"{current_doc}\n{fmt_section}\n"
+        new_doc = f"{current_doc.rstrip()}\n\n{fmt_section}\n"
 
     return new_doc
 

xsimlab/tests/test_formatting.py

@@ -43,35 +43,33 @@ def test_var_details(example_process_obj):
     assert "- dims : (('x',),)" in var_details_str
 
 
-def test_add_attribute_section():
-    """For testing, autodoc is set to False to avoid redundancy"""
+@xs.process(autodoc=False)
+class WithoutPlaceHolder:
+    """My process"""
+
+    var1 = xs.variable(dims="x", description="a variable")
+    var2 = xs.variable()
+
+
+@xs.process(autodoc=False)
+class WithPlaceholder:
+    """My process
 
-    @xs.process(autodoc=False)
-    class Dummy:
-        """This is a Dummy class
-    to test `add_attribute_section()`
-        """
-
-        var1 = xs.variable(dims="x", description="a variable")
-        var2 = xs.variable()
-
-    @xs.process(autodoc=False)
-    class Dummy_placeholder:
-        """This is a Dummy class
-    to test `add_attribute_section()`
-        
     {{attributes}}
-"""
 
-        var1 = xs.variable(dims="x", description="a variable")
-        var2 = xs.variable()
+    """
+
+    var1 = xs.variable(dims="x", description="a variable")
+    var2 = xs.variable()
+
+
+def test_add_attribute_section():
+    # For testing, autodoc is set to False to avoid redundancy
+    expected = """My process
 
-    expected = """This is a Dummy class
-    to test `add_attribute_section()`
-        
     Attributes
     ----------
-    var1 : object
+    var1 : :class:`attr.Attribute`
         A variable
 
         - type : variable
@@ -82,7 +80,7 @@ class Dummy_placeholder:
         - attrs : {}
         - encoding : {}
 
-    var2 : object
+    var2 : :class:`attr.Attribute`
         (no description given)
 
         - type : variable
@@ -92,11 +90,10 @@ class Dummy_placeholder:
         - static : False
         - attrs : {}
         - encoding : {}
+    """
 
-"""
-
-    assert add_attribute_section(Dummy) == expected
-    assert add_attribute_section(Dummy_placeholder) == expected
+    assert add_attribute_section(WithoutPlaceHolder).strip() == expected.strip()
+    assert add_attribute_section(WithPlaceholder).strip() == expected.strip()
 
 
 def test_process_repr(