Add Sphinx docs and GitHub Pages

Add an initial Sphinx documentation framework and a GitHub workflow to
auto-publish GitHub pages.

.github/workflows/docs.yml

@@ -0,0 +1,50 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
+      - name: Install dependencies
+        run: |
+          pip install .[ci]
+      - name: Sphinx build
+        run: |
+          nox -e docs
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          # Upload entire repository
+          path: 'docs/_build/'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.gitignore

@@ -57,3 +57,6 @@ ENV/
 env.bak/
 venv.bak/
 .ruff_cache/
+
+# Docs
+/docs/_build/

GNUmakefile

@@ -137,6 +137,7 @@ phonies+=rpm_build_source
 phonies+=rpm_package_source
 phonies+=ruff
 phonies+=synk
+phonies+=docs
 
 all : prepare rpm
 
@@ -158,10 +159,15 @@ help:
 	@echo '    rpm_build_source		Builds the SRPM.'
 	@echo '    rpm_package_source   Creates the RPM source tarball.'
 	@echo ''
+	@echo '	   docs					Generate Python sphinx documentation.'
 
 clean:
 	rm -rf build dist .ruff_cache
 
+docs:
+	sphinx-build -b html ./docs ./docs/_build
+
+
 #############################################################################
 # RPM targets
 #############################################################################

README.adoc

@@ -15,7 +15,6 @@ A library for Cray Systems Management.
 
 === Usage
 
-
 ==== Building and using `libcsm`
 
 * With `pip`
@@ -194,125 +193,6 @@ git+git://github.com/Cray-HPE/[email protected]#egg=libcsm
 git+git://github.com/Cray-HPE/libcsm.git@releases/tag/v1.0.1#egg=libcsm
 ----
 
-=== Versioning
-
-The version is derived from Git by the `setuptools_scm` Python module and follows https://peps.python.org/pep-0440/#abstract[PEP0440]'s version identification
-and dependency specification for https://peps.python.org/pep-0440/#final-releases[final] and https://peps.python.org/pep-0440/#pre-releases[pre] releases.
-
-.All Git-Tags in this repository are prefixed with `v`.
-
-==== Classification
-
-The items below denote how stable, pre-release, and unstable versions are classified through
-version strings.
-
-* **(stable) final release**: A git-tag following the `X.Y.Z` semver format is considered a final release version.
-+
-[source,bash]
-----
-# Format:
-# {tag}
-# X.Y.Z
-# X - Major
-# Y - Minor
-# Z - Micro (a.k.a. patch)
-0.1.2
-----
-* **(stable) post release**: A git-tag following the `X.Y.Z.postN` (where `N` is an integer), indicates a post-release.
-These are seldom used, and are strictly for handling documentation, packaging, or other meta
-updates after a release tag was already created where it isn't warranted to publish an
-entirely new release. `1.0.0.post0` and `1.0.0` are considered the same version in this repository. `1.0.0.post1` would
-produce an RPM with a release version of `2` (since our RPMs index their releases starting at `1`).
-+
-[source,bash]
-----
-# Format:
-# {tag}
-# X.Y.Z.postN
-# X - Major
-# Y - Minor
-# Z - Micro (a.k.a. patch)
-# Z - Post release [1-9]+
-0.1.2.post1
-----
-* **(unstable) pre-release**: A git-tag with an `a`(lpha), `b`(eta), or `r`(elease) `c`(andidate) annotation and an identification number `N` denotes a pre-release/preview.
-+
-.These are rarely used for `libcsm`.
-+
-[source,bash]
-----
-# Format:
-# {tag}[{a|b|rc}N]
-0.1.2a1
-0.1.2b1
-0.1.2rc1
-----
-* **(unstable) development**: Development builds **auto-increment** the micro version (the `Z` in `X.Y.Z`) or pre-release version (the `N` in `X.Y.Z{[a|b|rc]N}`), and 
-then append a suffix based on whether the working directory was **clean**, **dirty**, or **mixed**.
-** **clean**: When the version shows an appended `devN+{scm_letter}{revision_short_hash}`, that means there have been commits made since the previous git-tag.
-+
-[source,bash]
-----
-# Format:
-# {next_version}.dev{distance}+{scm_letter}{revision_short_hash}
-
-# If the previous git-tag was 0.1.2:
-           0.1.3.dev4+g818da8a
-
-# If the previous get-tag was a pre-release of 0.1.3a1:
-         0.1.3a2.dev4+g818da8a
-----
-** **dirty**: When the version shows an appended `.d{YYYYMMDD}` datestamp, that means there were modified/uncommitted changes in the working directory when the application was built.
-+
-[source,bash]
-----
-# Format:
-# {next_version}.d(datestamp}
-
-# If the previous git-tag was 0.1.2:
-           0.1.3.d20230123
-
-# If the previous get-tag was a pre-release of 0.1.3a1:
-         0.1.2a2.d20230123
-----
-** **mixed**: When the version shows a development tag with an appended datestamp, this means commits have been made but there were uncommitted changes present in the working directory when the application was built.
-+
-[source,bash]
-----
-# Format:
-# {next_Version}.dev{distance}+{scm_letter}{revision_short_hash}.d{datestamp}
-
-# If the previous git-tag was 0.1.2:
-           0.1.3.dev3+g3071655.d20230123
-
-# If the previous get-tag was a pre-release of 0.1.3a1:
-         0.1.3a2.dev3+g3071655.d20230123
-----
-
-For more information about versioning, see https://github.com/pypa/setuptools_scm/#default-versioning-scheme[versioning scheme information].
-
-==== Configuration
-
-The `setuptools_scm` module is configured by `pyproject.toml`.
-
-For more information regarding configuration of `setuptools_scm`, see https://github.com/pypa/setuptools_scm/#version-number-construction[version number construction].
-
-==== Retrieving the Python Package Version at Runtime
-
-If at any point code within the module wants to print or be aware of the modules own version, it can. The following snippet demonstrates how to do this.
-
-[source,python]
-----
-from importlib.metadata import version
-from importlib.metadata import PackageNotFoundError
-
-try:
-    __version__ = version("libcsm")
-except PackageNotFoundError:
-    # package is not installed
-    pass
-----
-
 === Contributing
 
 The primary purpose of the `libcsm` module is to support CSM installation, upgrade, and operational procedures. This module serves as a place for offering functions and error handling to common tasks

docs/conf.py

@@ -0,0 +1,61 @@
+#
+#  MIT License
+#
+#  (C) Copyright 2023 Hewlett Packard Enterprise Development LP
+#
+#  Permission is hereby granted, free of charge, to any person obtaining a
+#  copy of this software and associated documentation files (the "Software"),
+#  to deal in the Software without restriction, including without limitation
+#  the rights to use, copy, modify, merge, publish, distribute, sublicense,
+#  and/or sell copies of the Software, and to permit persons to whom the
+#  Software is furnished to do so, subject to the following conditions:
+#
+#  The above copyright notice and this permission notice shall be included
+#  in all copies or substantial portions of the Software.
+#
+#  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+#  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+#  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+#  THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+#  OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+#  ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+#  OTHER DEALINGS IN THE SOFTWARE.
+#
+
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+import os
+import sys
+from importlib.metadata import version
+from importlib.metadata import PackageNotFoundError
+try:
+    version = version('libcsm')
+except PackageNotFoundError:
+    pass
+
+sys.path.insert(0, os.path.abspath('..'))
+
+project = 'libCSM'
+copyright = '2023, Cray / HPE'
+author = 'Russell Bunch, Mitchell Tishmack, Jacob Salmela'
+
+# -- General configuration ---------------------------------------------------
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx_copybutton',
+    'sphinx_autodoc_typehints',
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+html_title = f"{project} Documentation ({version})"
+
+# -- Options for HTML output -------------------------------------------------
+html_theme = 'alabaster'
+html_static_path = ['_static']
+html_favicon = '_static/favicon.ico'
+html_logo = '_static/csm.jpeg'

docs/index.rst

@@ -0,0 +1,21 @@
+.. libCSM documentation master file, created by
+   sphinx-quickstart on Sat Apr 15 02:16:40 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+libCSM's documentation (|version|)
+==================================
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Contents:
+
+    libcsm
+    versioning
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/libcsm.rst

@@ -0,0 +1,11 @@
+API Reference
+=============
+
+.. automodule:: libcsm
+    :members:
+
+``api``
+-------
+
+.. automodule:: libcsm.api
+    :members: