Generate API documentation

doc/conf.py

@@ -46,6 +46,9 @@
     'sphinx.ext.githubpages',
     'sphinx_sitemap',
     'sphinx_reredirects',
+    'autoapi.extension',
+    'autodocsumm',
+    'sphinx.ext.napoleon'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -65,7 +68,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -75,15 +78,33 @@
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None
 
+# [Autoapi](https://sphinx-autoapi.readthedocs.io/) config
+autodoc_typehints = 'description'
+
+autodoc_default_options = {
+    'autosummary': True,
+}
+
+autoapi_dirs = ["../doit"]
+autoapi_options = [
+    'members',
+    'undoc-members',
+    'show-inheritance',
+    'show-module-summary',
+    'imported-members',
+]
+
+autoapi_keep_files = True
+
+# -- Options for HTML output -------------------------------------------------
+
 # non-default configuration for doit
 html_favicon = '_static/favico.ico'
 html_show_sourcelink = False
 html_extra_path = ['index.html', 'robots.txt', 'google726fc03ab55ebbfc.html']
 html_logo = '_static/doit-logo-small.png'
 
 
-# -- Options for HTML output -------------------------------------------------
-
 html_baseurl = 'https://pydoit.org'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

doc/contents.rst

@@ -66,6 +66,13 @@ Project
    related
 
 
+API Reference
+-------------
+
+.. toctree::
+   :maxdepth: 2
+
+   autoapi/index
 
 .. Indices and tables
    ==================

doc/index.html

@@ -49,9 +49,9 @@
             <button type="button" data-toggle="collapse" data-target="#navigation" class="navbar-toggler btn-template-outlined"><span class="sr-only">Toggle navigation</span><i class="fa fa-align-justify"></i></button>
             <div id="navigation" class="navbar-collapse collapse">
               <ul class="nav navbar-nav ml-auto">
-                <li class="nav-item menu-large"><a href="/contents.html">Docs</a></li>
+                <li class="nav-item menu-large"><a href="contents.html">Docs</a></li>
                 <li class="nav-item menu-large"><a href="https://github.com/pydoit/doit">Development</a>
-                <li class="nav-item menu-large"><a href="/support.html">Support</a></li>
+                <li class="nav-item menu-large"><a href="support.html">Support</a></li>
               </ul>
             </div>
           </div>

doit/action.py

@@ -15,7 +15,7 @@
 
 
 def normalize_callable(ref):
-    """return a list with (callable, *args, **kwargs)
+    """return a list with (``callable``, ``*args``, ``**kwargs``)
     ref can be a simple callable or a tuple
     """
     if isinstance(ref, tuple):
@@ -102,19 +102,19 @@ class CmdAction(BaseAction):
     """
     Command line action. Spawns a new process.
 
-    @ivar action(str,list,callable): subprocess command string or string list,
+    :ivar action(str,list,callable): subprocess command string or string list,
          see subprocess.Popen first argument.
          It may also be a callable that generates the command string.
          Strings may contain python mappings with the keys: dependencies,
          changed and targets. ie. "zip %(targets)s %(changed)s"
-    @ivar task(Task): reference to task that contains this action
-    @ivar save_out: (str) name used to save output in `values`
-    @ivar shell: use shell to execute command
-                 see subprocess.Popen `shell` attribute
-    @ivar encoding (str): encoding of the process output
-    @ivar decode_error (str): value for decode() `errors` param
+    :ivar task(Task): reference to task that contains this action
+    :ivar save_out: (str) name used to save output in ``values``
+    :ivar shell: use shell to execute command
+                 see subprocess.Popen ``shell`` attribute
+    :ivar encoding (str): encoding of the process output
+    :ivar decode_error (str): value for decode() ``errors`` param
                               while decoding process output
-    @ivar pkwargs: Popen arguments except 'stdout' and 'stderr'
+    :ivar pkwargs: Popen arguments except 'stdout' and 'stderr'
     """
 
     STRING_FORMAT = 'old'
@@ -181,22 +181,20 @@ def _print_process_output(self, process, input_, capture, realtime):
                 realtime.write(line)
                 realtime.flush()  # required if on byte buffering mode
 
-
     def execute(self, out=None, err=None):
         """
         Execute command action
 
         both stdout and stderr from the command are captured and saved
         on self.out/err. Real time output is controlled by parameters
-        @param out: None - no real time output
-                    a file like object (has write method)
-        @param err: idem
-        @return failure:
-            - None: if successful
-            - TaskError: If subprocess return code is greater than 125
-            - TaskFailed: If subprocess return code isn't zero (and
-        not greater than 125)
+        :param out: None - no real time output
+        :type out: file like object (has write method)
+        :param err: idem
+        :return: None: if successful,
+        TaskError: If subprocess return code is greater than 125,
+        TaskFailed: If subprocess return code isn't zero (and not greater than 125)
         """
+
         try:
             action = self.expand_action()
         except Exception as exc:
@@ -272,7 +270,7 @@ def execute(self, out=None, err=None):
 
     def expand_action(self):
         """Expand action using task meta informations if action is a string.
-        Convert `Path` elements to `str` if action is a list.
+        Convert ``Path`` elements to ``str`` if action is a list.
         @returns: string -> expanded string if action is a string
                   list - string -> expanded list of command elements
         """
@@ -300,8 +298,8 @@ def expand_action(self):
         }
 
         # dep_changed is set on get_status()
-        # Some commands (like `clean` also uses expand_args but do not
-        # uses get_status, so `changed` is not available.
+        # Some commands (like ``clean`` also uses expand_args but do not
+        # uses get_status, so ``changed`` is not available.
         if self.task.dep_changed is not None:
             subs_dict['changed'] = " ".join(self.task.dep_changed)