Example sphinx project using autodoc

.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+docs-out/

README.md

@@ -0,0 +1,51 @@
+# Example project
+
+Simple example that hopefully demonstrates how to use sphinx in autodoc.
+
+Map of important files:
+ - `docs/` -- Where all docs-related content is kept. It doesn't have to be in
+   its own folder, but it's a common convention.
+
+   - `conf.py` -- The configuration file for sphinx. See this file for more
+     details on how to configure Sphinx for use with autodoc.
+
+   - `index.rst` -- Root document that will become `index.html` in the generated
+     docs. It's conventional to put a `toctree` or at least some links to other
+     pages in the docs here.
+
+   - `module.rst` -- Where the autodoc for the example module is invoked.
+
+ - `src/` -- Where all the Python sources are kept. Also not a requirement to
+   have them separate, but a convention.
+
+   - `module/` -- The example module (in this case, a folder-type module with an
+     `__init__.py` specifying the exported names).
+
+      - `__init__.py` -- Entry point for the module specifying the exported
+        symbols. Sphinx autodoc uses this to figure out what parts of the module
+        to add to the docs.
+
+      - `module_class.py` -- Defines the Example class used to showcase the
+        autodoc features.
+
+  - `simple.py` -- A simple file-style module with a couple more exported names.
+
+## Running Sphinx
+
+First, make sure Sphinx is installed.
+
+```
+python3 -m pip install -r requirements.txt
+```
+
+Then, you can generate the docs:
+
+```
+sphinx-build -b html docs/ docs-out
+```
+
+And view them in your browser:
+
+```
+xdg-open docs-out/index.html
+```

docs/conf.py

@@ -0,0 +1,15 @@
+# Basic project metadata. This is used when generating the doc pages for things
+# like titles and footers.
+project = "Example"
+
+# This doc becomes `index.html` in the generated html docs
+master_doc = "index"
+
+# Sphinx autodoc will need to be able to import our module. Augmenting
+# `sys.path` with the path to the module ensures it can find it when we invoke
+# autodoc from a documentation file.
+import sys, os
+sys.path.append(os.path.join(os.path.dirname(__file__), "../src"))
+
+# Enable the autodoc extension
+extensions = ["sphinx.ext.autodoc"]

docs/index.rst

@@ -0,0 +1,6 @@
+Welcome to the Example docs!
+
+.. toctree::
+   simple
+   module
+

docs/module.rst

@@ -0,0 +1,8 @@
+Documentation for ``module``
+====================================
+
+Module is an example module that demonstrates the use of ``Autodoc``.
+
+.. automodule:: module
+   :members:
+

docs/requirements.txt

@@ -0,0 +1 @@
+sphinx

docs/simple.rst

@@ -0,0 +1,15 @@
+More info
+---------------------------------
+
+Here's a second file which could provide some detail on a particular module,
+class, or concept.
+
+It can include specific function docs here:
+
+.. autofunction:: math.log
+
+And here's the docs for our second module:
+
+.. automodule:: simple
+   :members:
+

src/module/__init__.py

@@ -0,0 +1,3 @@
+from .module_class import *
+
+__all__ = ["Example", "MODULE_CONST"]

src/module/module_class.py

@@ -0,0 +1,20 @@
+import sys
+import os
+
+
+MODULE_CONST = 1
+
+
+class Example:
+    """This is an example class which uses python docstrings to document itself.
+
+    It lives in :module:.
+    """
+
+    def foo(self, amount):
+        """Applies the well known ``foo`` operation to an instance of
+        :Example:.
+
+        :param: amount: How much foo to do.
+        """
+        self.amount = amount

src/simple.py

@@ -0,0 +1,8 @@
+
+__all__ = ["SIMPLE_CONST", "bar"]
+
+SIMPLE_CONST = 2
+
+def bar(a, b):
+    """Returns whether :a: and :b: have passed the bar exam in their state."""
+    return a + b > SIMPLE_CONST