Add documentation pipeline

.github/workflows/docs.yml

@@ -0,0 +1,33 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install hatch
+      - name: Generate Docs
+        run: |
+          hatch run generate-docs
+      - name: Deploy Docs
+        uses: JamesIves/github-pages-deploy-action@v4.4.1
+        if: github.event_name != 'pull_request'
+        with:
+          clean: false
+          branch: gh-pages
+          folder: docs/_build

.gitignore

@@ -5,3 +5,4 @@ example/.outpack/index/outpack.rds
 example/draft/
 .idea
 /dist
+docs/_build

docs/code.md

@@ -0,0 +1,25 @@
+# Code examples
+
+Giving a short explanation here for function:
+
+(add_function)=
+## Add Function
+
+```python
+def add(x, y):
+    return x + y
+```
+
+just like normal markdown baby
+
+```{warning}
+Easy there buckaroo
+```
+
+```{error}
+No can do
+```
+
+```{note}
+For your information
+```

docs/conf.py

@@ -0,0 +1,49 @@
+# 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 -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+import outpack.__about__ as info
+
+project = info.__name__
+copyright = "2023-present Imperial College of Science, Technology and Medicine"
+author = "Rich FitzJohn"
+release = info.__version__
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx_rtd_theme",
+    "autoapi.extension",
+    "myst_parser",
+    "sphinx.ext.autosectionlabel",
+    "sphinx_copybutton",
+]
+
+autoapi_dirs = ["../src"]
+autoapi_options = [
+    "members",
+    "undoc-members",
+    "show-inheritance",
+    "show-module-summary",
+    "special-members",
+    "imported-members",
+]
+
+copybutton_prompt_text = (
+    r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
+)
+copybutton_prompt_is_regexp = True
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]

docs/index.md

@@ -0,0 +1,18 @@
+# Welcome to outpack-py's documentation!
+
+```{toctree}
+:maxdepth: 2
+:caption: 'Contents:'
+
+readme
+code
+```
+
+% uses MyST markdown format https://jupyterbook.org/en/stable/content/myst.html
+
+Also inserting a reference to a function defined in the code file [here](add_function).
+
+Alternative way of referencing is {ref}`Add Function` (each section has an automatic ref generated for it,
+it matches the name of the section).
+
+We can also link a document, here I will link {doc}`readme`

docs/readme.md

@@ -0,0 +1,3 @@
+```{include} ../README.md
+:relative-images:
+```

pyproject.toml

@@ -43,6 +43,11 @@ path = "src/outpack/__about__.py"
 dependencies = [
   "coverage[toml]>=6.5",
   "pytest",
+  "sphinx",
+  "sphinx-rtd-theme",
+  "myst-parser",
+  "sphinx-copybutton",
+  "sphinx-autoapi"
 ]
 [tool.hatch.envs.default.scripts]
 test = "pytest {args:tests}"
@@ -63,7 +68,10 @@ cov-ci = [
   "test-cov",
   "cov-report-xml",
 ]
-
+generate-docs = [
+  "sphinx-autogen ./docs/*.md",
+  "sphinx-build -b html ./docs ./docs/_build"
+]
 
 [[tool.hatch.envs.all.matrix]]
 python = ["3.7", "3.8", "3.9", "3.10", "3.11"]

src/outpack/__about__.py

@@ -2,3 +2,4 @@
 #
 # SPDX-License-Identifier: MIT
 __version__ = "0.0.1"
+__name__ = "outpack-py"