Merge pull request #31 from matthewhughes934/generate-docs-from-pydocs

Add a 'reference' documentation section

.github/workflows/test.yml

@@ -38,3 +38,9 @@ jobs:
           flags: py${{ matrix.python-version }}
           fail_ci_if_error: true
           verbose: true
+      - name: Install docs dependencies
+        working-directory: docs
+        run: pip install --requirement requirements.txt
+      - name: Build docs
+        working-directory: docs
+        run: make html

docs/conf.py

@@ -10,9 +10,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
 
 
 # -- Project information -----------------------------------------------------
@@ -31,6 +31,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinx.ext.autodoc',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/index.rst

@@ -5,6 +5,10 @@ Python threaded IMAP4 client module ``imaplib2``
    :maxdepth: 2
    :caption: Contents:
 
+   reference
+
+.. contents:: :local:
+
 This module defines a class, ``IMAP4``, which encapsulates a threaded
 connection to an IMAP4 server and implements the IMAP4rev1 client
 protocol as defined in RFC 3501 with several extensions. This module

docs/reference.rst

@@ -0,0 +1,4 @@
+Library Reference
+=================
+
+.. autofunction:: imaplib2.version

imaplib2/imaplib2.py

@@ -139,17 +139,15 @@
 
 
 def version(use_tuple=False):
-    """Return the version of this module.
-
-    Arguments
-    ---------
-    use_tuple : bool
-        Whether to return a string or a tuple of (major, minor). When True, the major and minor in the tuple will be
-        integers rather than strings.
-
-    Returns
-    -------
-    The version.
+    """
+    Return the version of this module, either as a single string (the default) or a :class:`tuple`
+    of ``major_version, minor_version`` as integers
+
+    :param use_tuple: Whether to return :class:`tuple`
+    :type use_tuple: :class:`bool`
+    :return: The version of this library, the format depends on the value of ``use_tuple``
+    :rtype: (:class:`int`, :class:`int`) if ``use_tuple``
+    :rtype: :class:`str` otherwise
     """
 
     if use_tuple: