RST-formatted documentation, guides, and related bug fixes

.github/workflows/Sphinx.yaml

@@ -30,6 +30,12 @@ jobs:
           REWRITE_DEPENDENCIES=true \
             make Sphinx-html
 
+      - name: Upload static files as artifact
+        id: deployment
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: sphinx-docs/build/html/
+
   deploy:
     needs: build
 

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "Ligare.wiki"]
+	path = Ligare.wiki
+	url = https://github.com/uclahs-cds/Ligare.wiki.git

Makefile

@@ -30,7 +30,7 @@ PYPI_REPO ?= testpypi
 REPORTS_DIR ?= reports
 BANDIT_REPORT := bandit.sarif
 PYTEST_REPORT := pytest
-PYTEST_TARGET ?= .
+PYTEST_TARGET ?= 'src test'
 TOX_DIR := .tox
 
 
@@ -256,3 +256,27 @@ reset-check:
 reset : reset-check clean
 	git checkout -- $(PYPROJECT_FILES)
 
+
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+Sphinx-help: $(VENV) $(DEFAULT_TARGET)
+	@$(ACTIVATE_VENV) && \
+	$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: Sphinx-help Makefile
+
+Sphinx: $(VENV) $(DEFAULT_TARGET) Makefile
+	$(MAKE) Sphinx-html
+
+Sphinx-%: $(VENV) $(DEFAULT_TARGET) Makefile
+	$(ACTIVATE_VENV) && \
+	$(SPHINXBUILD) -M $(patsubst Sphinx-%,%,$@) "sphinx-docs/$(SOURCEDIR)" "sphinx-docs/$(BUILDDIR)" $(SPHINXOPTS)
+
+Sphinx-autobuild: $(VENV) $(DEFAULT_TARGET) Makefile
+	$(ACTIVATE_VENV) && \
+	sphinx-autobuild "sphinx-docs/$(SOURCEDIR)" "sphinx-docs/$(BUILDDIR)/html" \
+	    --watch src/ --ignore "!src/**/*.py" --ignore "src/*/test/**" \
+		-j auto

examples/cli-app/app/__main__.py

@@ -0,0 +1,31 @@
+from injector import inject
+from Ligare.programming.application import ApplicationBase, ApplicationBuilder
+from Ligare.programming.config import Config
+from typing_extensions import override
+
+
+class Application(ApplicationBase):
+    @inject
+    @override
+    def run(self, config: "AppConfig"):
+        print(config.message)
+        input("\nPress anything to exit. ")
+
+
+builder = ApplicationBuilder(Application)
+
+
+class AppConfig(Config):
+    message: str
+
+
+builder.use_configuration(
+    lambda config_builder: config_builder \
+        .with_config_type(AppConfig) \
+        .with_config_filename("app/config.toml")
+)
+
+application = builder.build()
+
+if __name__ == "__main__":
+    application.run()

examples/cli-app/app/config.toml

@@ -0,0 +1,2 @@
+[app]
+message = "Hello, world!"

examples/cli-app/pyproject.toml

@@ -0,0 +1,7 @@
+[project]
+requires-python = ">= 3.10"
+
+name = "cli-app"
+version = "0.0.1"
+
+dependencies = ["Ligare.programming"]

examples/web-api/app/__main__.py

@@ -0,0 +1,15 @@
+from Ligare.web.application import ApplicationBuilder
+from connexion import FlaskApp
+
+application_builder = ApplicationBuilder(FlaskApp)
+
+application_builder.use_configuration(
+    lambda config_builder: \
+        config_builder \
+            .with_config_filename("app/config.toml")
+)
+
+application = application_builder.build()
+
+if __name__ == "__main__":
+    application.run()

examples/web-api/app/config.toml

@@ -0,0 +1,8 @@
+[logging]
+format = 'plaintext'
+
+[flask]
+app_name = 'app'
+
+[flask.openapi]
+spec_path = 'openapi.yaml'

examples/web-api/app/openapi.yaml

@@ -0,0 +1,16 @@
+info:
+  title: Test Application
+  version: 3.0.3
+openapi: 3.0.3
+paths:
+  /:
+    get:
+      description: Say "Hello, World!"
+      operationId: app.root.get
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                type: string
+          description: Said "Hello, World!" successfully

examples/web-api/app/root.py

@@ -0,0 +1,2 @@
+def get():
+    return "Hello, World!"

examples/web-api/pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+requires-python = ">= 3.10"
+
+name = "web-api"
+version = "0.0.1"
+
+dependencies = [
+    "Ligare.web"
+]

pyproject.toml

@@ -92,7 +92,19 @@ dev-dependencies = [
     "pyright == 1.1.391",
     "isort ~= 5.13",
     "ruff ~= 0.3",
-    "bandit[sarif,toml] ~= 1.7"
+    "bandit[sarif,toml] ~= 1.7",
+    "sphinx",
+    "sphinx-autodoc-typehints",
+    "sphinx_toolbox",
+    "sphinx-rtd-theme",
+    "sphinx-copybutton",
+    "sphinx-autobuild"
+]
+
+# Install if you want to use the Esbonio extension
+# in VSCode to write reStructuredText documents.
+vscode-sphinx = [
+    "esbonio"
 ]
 
 [tool.pyright]
@@ -113,7 +125,11 @@ exclude = [
     ".git",
     "**/typings",
     "**/node_modules",
-    "**/__pycache__"
+    "**/__pycache__",
+    "docs",
+    "sphinx-docs",
+    "examples",
+    "Ligare.wiki"
 ]
 
 extraPaths = [
@@ -191,7 +207,7 @@ addopts = [
 
 python_files = "test_*.py"
 
-norecursedirs = "__pycache__ build .pytest_cache *.egg-info .venv .github-venv"
+norecursedirs = "__pycache__ build .pytest_cache *.egg-info .venv .github-venv docs sphinx-docs examples Ligare.wiki"
 
 [tool.tox]
 legacy_tox_ini = """
@@ -242,7 +258,11 @@ omit = [
     "*/typings/*",
     "node_modules/*",
     "__pycache__/*",
-    "*/__pycache__/*"
+    "*/__pycache__/*",
+    "docs/*",
+    "sphinx-docs",
+    "examples",
+    "Ligare.wiki"
 ]
 branch = true
 
@@ -256,9 +276,16 @@ exclude_dirs = [
     "./__pycache__/*",
     "./.github/*",
     "./.venv/*",
+    ".venv", # ignore any deeper .venv dirs too
+    "./.tox/*",
+    ".git",
     "./.git/*",
     "./test/*/test*.py",
-    "./src/*/test/*/test*.py"
+    "./src/*/test/*/test*.py",
+    "./docs/*",
+    "./sphinx-docs/*",
+    "./examples/*",
+    "./Ligare.wiki/*"
 ]
 
 [tool.ruff]

sphinx-docs/.gitignore

@@ -0,0 +1 @@
+source/source/generated/*.rst

sphinx-docs/source/_static/custom.css

@@ -0,0 +1,12 @@
+/* change `..code-block:: shell-session` prompt appearance */
+.highlight .gp {
+    color: #616161;
+    font-style: italic;
+}
+
+/* put `literalinclude` captions on the left and closer to coe blocks */
+.rst-content .literal-block-wrapper .code-block-caption {
+    text-align: left;
+    padding-bottom: 0.5em;
+    margin-top: -1.5em;
+}