Add plugin support for Numpy-style docstrings, and some minor docstri…

…ng syntax fixes
tkrajina · May 20, 2022 · bb75193 · bb75193
1 parent d08cbe8
commit bb75193
Show file tree

Hide file tree

Showing 4 changed files with 11 additions and 5 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -26,12 +26,18 @@
 # Sphinx extension modules
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
     'sphinx_autodoc_typehints',
     'sphinxcontrib.apidoc',
     'm2r2',
 ]
 
+# Enable Numpy-style docstrings
+napoleon_numpy_docstring = True
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = False
+
 # Use sphinx-apidoc to auto-generate rst sources
 # Configured here instead of instead of in Makefile so it will be used by ReadTheDocs
 apidoc_module_dir = PACKAGE_DIR

diff --git a/gpxpy/__init__.py b/gpxpy/__init__.py
@@ -21,7 +21,7 @@
 def parse(xml_or_file: Union[AnyStr, IO[str]], version: Optional[str] = None) -> mod_gpx.GPX:
     """
     Parse xml (string) or file object. This is just an wrapper for
-    GPXParser.parse() function.
+    :py:meth:`GPXParser.parse`.
 
     parser may be 'lxml', 'minidom' or None (then it will be automatically
     detected, lxml if possible).

diff --git a/gpxpy/gpx.py b/gpxpy/gpx.py
@@ -411,7 +411,7 @@ def length(self) -> float:
         """
         Computes length (2-dimensional) of route.
 
-        Returns:
+        Returns
         -----------
         length: float
             Length returned in meters
@@ -928,7 +928,7 @@ def get_time_bounds(self) -> TimeBounds:
         """
         Gets the time bound (start and end) of the segment.
 
-        returns
+        Returns
         ----------
         time_bounds : TimeBounds named tuple
             start_time : datetime

diff --git a/gpxpy/gpxfield.py b/gpxpy/gpxfield.py
@@ -311,8 +311,8 @@ def to_xml(self, value: Any, version: str, nsmap: Optional[Dict[str, str]]=None,
             version: str of the gpx output version "1.0" or "1.1"
 
         Returns:
-            None if value is empty or str of XML representation of the
-            address. Representation starts with a \n.
+            None if value is empty or str of XML representation of the address.
+            Representation starts with ``\\n``.
         """
         if not value:
             return ''