Updating demo

Author: jramsdell-bt

.DS_Store

@@ -13,7 +13,7 @@ jobs:
       - uses: actions/setup-python@v3
       - name: Install dependencies
         run: |
-          pip install sphinx sphinx_rtd_theme pydata-sphinx-theme sphinx-design sphinx-copybutton
+          pip install sphinx pydata-sphinx-theme sphinx-design sphinx-copybutton sphinx-autoapi
       - name: Sphinx build
         run: |
           sphinx-build docs _build

.github/workflows/documentation.yml

@@ -0,0 +1,4 @@
+_build
+.venv
+sphinx_venv
+*.pyc

.gitignore

@@ -0,0 +1,8 @@
+Basic Example
+=============
+
+
+Example of displaying API:
+
+.. automodule:: example
+    :members:

docs/api/api_base.rst

@@ -0,0 +1,9 @@
+API
+===
+
+This contains API
+
+
+.. toctree::
+
+    api_base

docs/api/index.rst

@@ -1,3 +1,7 @@
+# import sys
+# import os
+# sys.path.insert(0, os.path.abspath('../'))
+
 # Configuration file for the Sphinx documentation builder.
 #
 # This file only contains a selection of the most common options. For a full
@@ -24,10 +28,19 @@
 extensions = [
     "sphinx.ext.githubpages", # used for hosting on GitHub Pages
     "sphinx.ext.todo",
+    "autoapi.extension",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
     "sphinx_copybutton", # adds a copy button to source code blocks
     "sphinx_design"
 ]
 
+# For API documentation
+autoapi_dirs = ["../testpackage"]
+autoapi_add_toctree_entry = False
+autodoc_typehints = 'description'
+
+
 # Settings for myst_nb:
 # https://myst-nb.readthedocs.io/en/latest/use/execute.html#triggering-notebook-execution
 nb_execution_mode = "cache"

docs/conf.py

@@ -39,7 +39,7 @@ It's a good idea to install them in a **virtual environment**.
 3. Building Documentation
 -------------------------
 The documentation for the :code:`sphinx-documentation-demo` is located in :code:`docs/`.
-To build this documentation, while in the project directory, do:
+While in the root project directory, do:
 
 .. code-block:: bash
 
@@ -55,15 +55,13 @@ You can open the file :code:`docs/index.html` on your computer to view the HTML
 The :code:`sphinx-autobuild` extension allows us to build local documentation whenever we make changes.
 It also refreshes the web browser so you can see the changes "live". This makes it **very convenient for rapid development**.
 
-This extension has already been included in the :code:`requirements.txt` file
-
 While in the virtual environment, run the following command:
 
 .. code-block:: bash
 
     sphinx-autobuild docs _build
 
-This will create a local host instance which you can then access through your web browser (you can just copy/paste the http address you get from :code:`sphinx-autobuild`)
+You can then point your web browser to: http://127.0.0.1:8000/
 
 Remote Build on GitHub
 ======================

docs/guides/.DS_Store

@@ -109,7 +109,7 @@ Right Navigation Bar
 
 
 The right navigation bar allows users to navigation between **different sections within the current page**.
-This is automatically generated based on section headers specified within the page's :term:'rST' file.
+This is automatically generated based on section headers specified within the page's :term:`rST` file.
 
 ..
     .. image:: images/tab2_top.png

docs/guides/guide_installation.rst

@@ -6,6 +6,7 @@ This is the root directory.
    :maxdepth: 1
 
    guides/index
+   autoapi/testpackage/index
    tab_2/index
    tab_3/index
 

docs/guides/layout/images/.DS_Store

@@ -0,0 +1,10 @@
+[project]
+name = "sphinx-documentation-demo"
+dynamic = ["version"]
+dependencies = [
+    "pydata-sphinx-theme==0.15.2",
+    "Sphinx==7.2.6",
+    "sphinx-autobuild==2024.2.4",
+    "sphinx_copybutton",
+    "sphinx_design==0.5.0"
+]

docs/guides/layout/layout_basic.rst

@@ -2,3 +2,4 @@ pydata-sphinx-theme==0.15.2
 Sphinx==7.2.6
 sphinx-autobuild==2024.2.4
 sphinx_design==0.5.0
+sphinx_copybutton

docs/index.rst

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+class TestMessage(object):
+    """This is the docstring for the TestMessage class.
+
+    Args:
+        message_string (string): String to be printed later
+    """
+    def __init__(self, message_string: str):
+        self.message_string = message_string
+
+    @staticmethod
+    def from_number(number: int) -> TestMessage:
+        """Creates a TestMessage from the provided number.
+
+        Args:
+            number: the number to convert into a string
+        """
+
+        return TestMessage(message_string=str(number))
+

pyproject.toml

@@ -0,0 +1,27 @@
+from __future__ import annotations
+from testpackage.test_message import TestMessage
+
+class TestPrinter(object):
+    """This is the docstring for TestPrinter
+    Stuff
+    
+    Args:
+        msg: Message to be stored for later printing
+    """
+
+    def __init__(self, msg: TestMessage):
+        self.msg = msg
+
+
+    def print(self) -> None:
+        """This function is used to print the stored message.
+        """
+        print(self.msg.message_string)
+
+
+def function_within_package() -> None:
+    """This is just an example of a function within a package 
+    that is not also contained within a class.
+    """
+    print("This is a test function")
+