Switched to Google style docstrings

autoapi/extension.py

@@ -65,9 +65,7 @@ def _normalise_autoapi_dirs(autoapi_dirs, srcdir):
 
 
 def run_autoapi(app):  # pylint: disable=too-many-branches
-    """
-    Load AutoAPI data from the filesystem.
-    """
+    """Load AutoAPI data from the filesystem."""
     if app.config.autoapi_type not in LANGUAGE_MAPPERS:
         allowed = ", ".join(f'"{api_type}"' for api_type in sorted(LANGUAGE_MAPPERS))
         raise ExtensionError(
@@ -178,9 +176,7 @@ def source_read(app, docname, source):  # pylint: disable=unused-argument
 
 
 def doctree_read(app, doctree):
-    """
-    Inject AutoAPI into the TOC Tree dynamically.
-    """
+    """Inject AutoAPI into the TOC Tree dynamically."""
 
     if app.env.docname == "index":
         all_docs = set()

autoapi/mappers/base.py

@@ -20,31 +20,32 @@
 
 class PythonMapperBase:
 
-    """
-    Base object for JSON -> Python object mapping.
+    """Base object for JSON -> Python object mapping.
 
     Subclasses of this object will handle their language specific JSON input,
     and map that onto this standard Python object.
     Subclasses may also include language-specific attributes on this object.
 
     Arguments:
 
-    :param obj: JSON object representing this object
-    :param jinja_env: A template environment for rendering this object
+    Args:
+        obj: JSON object representing this object
+        jinja_env: A template environment for rendering this object
 
     Required attributes:
 
-    :var str id: A globally unique identifier for this object.
-                 Generally a fully qualified name, including namespace.
-    :var str name: A short "display friendly" name for this object.
+    Attributes:
+        id (str): A globally unique identifier for this object.
+            Generally a fully qualified name, including namespace.
+        name (str): A short "display friendly" name for this object.
+        docstring (str): The documentation for this object
+        imports (list): Imports in this object
+        children (list): Children of this object
+        parameters (list): Parameters to this object
+        methods (list): Methods on this object
 
     Optional attributes:
 
-    :var str docstring: The documentation for this object
-    :var list imports: Imports in this object
-    :var list children: Children of this object
-    :var list parameters: Parameters to this object
-    :var list methods: Methods on this object
     """
 
     language = "base"
@@ -164,8 +165,8 @@ class SphinxMapperBase:
 
     """Base class for mapping `PythonMapperBase` objects to Sphinx.
 
-    :param app: Sphinx application instance
-
+    Args:
+        app: Sphinx application instance
     """
 
     def __init__(self, app, template_dir=None, url_root=None):
@@ -204,10 +205,7 @@ def _wrapped_prepare(value):
         self.top_level_objects = OrderedDict()
 
     def load(self, patterns, dirs, ignore=None):
-        """
-        Load objects from the filesystem into the ``paths`` dictionary.
-
-        """
+        """Load objects from the filesystem into the ``paths`` dictionary."""
         paths = list(self.find_files(patterns=patterns, dirs=dirs, ignore=ignore))
         for path in sphinx.util.status_iterator(
             paths,
@@ -270,17 +268,18 @@ def find_files(patterns, dirs, ignore):
     def read_file(self, path, **kwargs):
         """Read file input into memory
 
-        :param path: Path of file to read
+        Args:
+            path: Path of file to read
         """
         # TODO support JSON here
         # TODO sphinx way of reporting errors in logs?
         raise NotImplementedError
 
     def add_object(self, obj):
-        """
-        Add object to local and app environment storage
+        """Add object to local and app environment storage
 
-        :param obj: Instance of a AutoAPI object
+        Args:
+            obj: Instance of a AutoAPI object
         """
         self.objects[obj.id] = obj
         self.all_objects[obj.id] = obj
@@ -302,10 +301,10 @@ def map(self, options=None):
                 self.add_object(obj)
 
     def create_class(self, data, options=None, **kwargs):
-        """
-        Create class object.
+        """Create class object.
 
-        :param data: Instance of a AutoAPI object
+        Args:
+            data: Instance of a AutoAPI object
         """
         raise NotImplementedError
 

autoapi/mappers/dotnet.py

@@ -285,8 +285,9 @@ class DotNetPythonMapper(PythonMapperBase):
 
     """Base .NET object representation
 
-    :param references: object reference list from docfx
-    :type references: list of dict objects
+    Args:
+        references (list of dict objects): object reference list from
+            docfx
     """
 
     language = "dotnet"
@@ -446,14 +447,13 @@ def ref_short_name(self):
 
     @staticmethod
     def transform_doc_comments(text):
-        """
-        Parse XML content for references and other syntax.
+        """Parse XML content for references and other syntax.
 
         This avoids an LXML dependency, we only need to parse out a small subset
         of elements here. Iterate over string to reduce regex pattern complexity
         and make substitutions easier
 
-        .. seealso::
+        See Also:
 
             `Doc comment reference <https://msdn.microsoft.com/en-us/library/5ast78ax.aspx>`
                 Reference on XML documentation comment syntax
@@ -514,13 +514,15 @@ def resolve_spec_identifier(self, obj_name):
         a compound reference that should be linked in a special way. Resolve to
         a nested reference, with the corrected nodes.
 
-        .. note::
+        Note:
             This uses a special format that is interpreted by the domain for
             parameter type and return type fields.
 
-        :param obj_name: spec identifier to resolve to a correct reference
-        :returns: resolved string with one or more references
-        :rtype: str
+        Args:
+            obj_name: spec identifier to resolve to a correct reference
+
+        Returns:
+            str: resolved string with one or more references
         """
         ref = self.references.get(obj_name)
         if ref is None: