Fix: use auto-api

Author: lwasser

docs/conf.py

@@ -36,6 +36,10 @@
 # Extensions add additional functionality to your documentation.
 # TODO: describe each extension below
 extensions = [
+    # Autodoc will create API docs for you
+    # "sphinx.ext.autodoc", # This is the older autodoc that doesn't support myst
+    "autodoc2",  # Supports myst markdown, ugly output
+    "autoapi.extension",
     "sphinx_design",
     "sphinx_copybutton",
     "sphinx.ext.intersphinx",
@@ -64,3 +68,11 @@
 
 html_theme = "pydata_sphinx_theme"
 html_static_path = ["_static"]
+
+# Autodoc
+# autodoc2_render_plugin = "myst"
+# autodoc2_packages = [
+#     "../src/pyospackage",
+# ]
+
+autoapi_dirs = ["../src/pyospackage"]

docs/documentation/setup-sphinx.md

@@ -19,14 +19,14 @@ Below is the Sphinx-quickstart workflow used to create these docs. However,
 inevitably you will likely customize the documentation setup. So you may also
 want to just copy this repository's structure.
 
-```
+```bash
 ➜ sphinx-quickstart
 Welcome to the Sphinx 5.3.0 quickstart utility.
 
 Please enter values for the following settings (just press Enter to
 accept a default value, if one is given in brackets).
 
-Selected root path: .
+Selected root path: docs
 
 You have two options for placing the build directory for Sphinx output.
 Either, you use a directory "_build" within the root path, or you separate
@@ -47,5 +47,21 @@ https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
 > Project language [en]: en
 ```
 
-The `conf.py` file is the core that you use to configure your sphinx docs.
-The conf.py file in this package is setup
+## About the conf.py file
+
+The `conf.py` file is what Sphinx uses to configure your documentation. This is
+where you setup all of the features that you want your documentation to have.
+
+:::{note}
+Every tool and theme that you might use will have different configuration options
+that will be placed in the `conf.py` file.
+:::
+
+## API / Reference documentation
+
+It's useful to have a reference section in your docs that contains documentation
+for your package's methods and classes. In this demo package we are using
+autodoc2 which will create these reference docs for you automatically.
+
+We like `autodoc2` over `sphinx_autodoc` extension because it supports `myst`
+markdown.

docs/index.md

@@ -7,6 +7,7 @@
 home <self>
 hatch scripts <hatch-envs-scripts>
 Setup Sphinx <documentation/setup-sphinx>
+Reference / API <apidocs/index>
 :::
 
 :::{toctree}

pyproject.toml

@@ -42,6 +42,9 @@ dependencies = [
   "sphinx-copybutton",
   "myst-nb",
   "myst-parser",
+  "sphinx-autoapi",
+  # Autodoc2 supports myst mardown
+  #"sphinx-autodoc2"
 ]
 
 

src/pyospackage/add_numbers.py

@@ -5,4 +5,18 @@ def add_num(
     a: int,
     b: int,
 ) -> int:
+    """A function that adds two  numbers together
+
+    Parameters
+    ----------
+    a : int
+        The first integer to be added.
+    b : int
+        The second integer to be added.
+
+    Returns
+    -------
+    int
+        The sum of the two provided integers.
+    """
     return a + b