Merge pull request #123 from sudlab/ns-rse/122-mkdocs-how-to-add-func…

…tions

docs: Switches to mkdocs for building and deploying documentation

.github/workflows/mkdocs-deploy.yaml

@@ -0,0 +1,18 @@
+name: Publish docs via GitHub Pages
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout master
+        uses: actions/checkout@v1
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -176,4 +176,6 @@ cython_debug/
 .dir-locals.el
 
 # pytest-testmon
-.testmon*
+.testmon*
+
+tmp/

.markdownlint-cli2.yaml

@@ -15,6 +15,7 @@ globs:
 
 ignores:
   - "tmp/**/*.md"
+  - "docs/api/**/*.md"
 
 # Fix any fixable errors
 fix: true

docs/api.md

@@ -0,0 +1,8 @@
+# API
+
+- [`io`](api/io.md)
+- [`isoslam`](api/isoslam.md)
+- [`logging`](api/logging.md)
+- [`processing`](api/processing.md)
+- [`summary`](api/summary.md)
+- [`utils`](api/utils.md)

docs/api/io.md

@@ -0,0 +1,9 @@
+# IO Modules
+
+::: isoslam.io
+handler: python
+options:
+docstring_style:
+numpy
+rendering:
+show_signature_annotations: true

docs/api/isoslam.md

@@ -0,0 +1,11 @@
+# IsoSLAM
+
+This module contains the main functions that constitute the IsoSLAM package.
+
+::: isoslam.isoslam
+handler: python
+options:
+docstring_style:
+numpy
+rendering:
+show_signature_annotations: true

docs/api/logging.md

@@ -0,0 +1,11 @@
+# Logging
+
+This module handles logging setup.
+
+::: isoslam.logging
+handler: python
+options:
+docstring_style:
+numpy
+rendering:
+show_signature_annotations: true

docs/api/processing.md

@@ -0,0 +1,9 @@
+# Processing
+
+::: isoslam.processing
+handler: python
+options:
+docstring_style:
+numpy
+rendering:
+show_signature_annotations: true

docs/api/summary.md

@@ -0,0 +1,9 @@
+# Summary
+
+::: isoslam.summary
+handler: python
+options:
+docstring_style:
+numpy
+rendering:
+show_signature_annotations: true

docs/api/utils.md

@@ -0,0 +1,11 @@
+# Utils
+
+This module contains various utilities used within the package.
+
+::: isoslam.utils
+handler: python
+options:
+docstring_style:
+numpy
+rendering:
+show_signature_annotations: true

docs/source/contributing.md → docs/contributing.md

@@ -59,7 +59,7 @@ pip install --no-cache-dir -e .[docs,dev]
 ## Git
 
 [Git][git] is used to version control development of the package. The `main` branch on GitHub and the [pre-commit
-hooks](contributing#pre-commit) have protections in place that prevent committing/pushing directly to the `main`
+hooks](#pre-commit) have protections in place that prevent committing/pushing directly to the `main`
 branch. This means you should create a branch to undertake development or fix bugs.
 
 ### Issues