Improve API documentation

Author: eltos

docs/conf.py

@@ -42,6 +42,8 @@
 
 def autoapi_skip_member(app, what, name, obj, skip, options):
     skip |= ".. deprecated::" in obj.docstring
+    skip |= ":nodoc:" in obj.docstring
+    skip |= not obj.docstring and what == "data"  # undocumented variables
     return skip
 
 

xplt/colors.py

@@ -31,30 +31,31 @@
     "#717581",
     "#92dadd",
 ]
+"""List of 10 accessible and aesthetic colors selected by M. A. Petroff"""
 
-#: Colormap with 10 distinct colors
 cmap_petroff = mpl.colors.ListedColormap(petroff_colors, "petroff")
+"""Colormap with 10 distinct colors"""
 cmap_petroff.set_under("none")
 cmap_petroff.set_over("none")
 
-#: Gradient colormap
 cmap_petroff_gradient = mpl.colors.LinearSegmentedColormap.from_list(
     "petroff_gradient", [petroff_colors[i] for i in (9, 0, 4, 2, 6, 1)]
 )
+"""Gradient colormap"""
 cmap_petroff_gradient.set_under(petroff_colors[3])
 cmap_petroff_gradient.set_over(petroff_colors[7])
 
-#: Bipolar colormap
 cmap_petroff_bipolar = mpl.colors.LinearSegmentedColormap.from_list(
     "petroff_bipolar", [petroff_colors[i] for i in (2, 6, 1, 3, 9, 0, 4)]
 )
+"""Bipolar colormap"""
 cmap_petroff_bipolar.set_under(petroff_colors[5])
 cmap_petroff_bipolar.set_over(petroff_colors[8])
 
-#: Cyclic colormap
 cmap_petroff_cyclic = mpl.colors.LinearSegmentedColormap.from_list(
     "petroff_cyclic", [petroff_colors[i] for i in (3, 9, 0, 4, 2, 6, 1, 3)]
 )
+"""Cyclic colormap"""
 
 
 def make_unicoloured_cmap(color):

xplt/util.py

@@ -23,13 +23,19 @@
 
 
 def PUBLIC_SECTION_BEGIN():
-    """Starting from here, collect objects to be included in file's `__all__` magic"""
+    """Starting from here, collect objects to be included in file's `__all__` magic
+
+    :nodoc:
+    """
     g = inspect.stack()[1].frame.f_globals
     g["__private_names"] = set(g.keys()).union(["__private_names"])
 
 
 def PUBLIC_SECTION_END():
-    """Finish object collection and return global names for the `__all__` magic"""
+    """Finish object collection and return global names for the `__all__` magic
+
+    :nodoc:
+    """
     g = inspect.stack()[1].frame.f_globals
     public = list(set(g.keys()).difference(g["__private_names"]))
     return public[:]  # copy needed for it to work with sphinx autoapi
@@ -38,7 +44,8 @@ def PUBLIC_SECTION_END():
 VOID = object()
 
 
-c0 = 299792458  # speed of light in m/s
+c0 = 299792458
+"""Speed of light in m/s"""
 
 
 def val(obj):