Develop

.github/workflows/docs.yml

@@ -0,0 +1,41 @@
+name: Deploy Sphinx docs to Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "src/pmotools/**"
+      - "man/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: |
+          pip install -e .
+          pip install -r man/requirements.txt
+      - name: Regenerate autodocs and build
+        run: |
+          cd man
+          make update_autodocs
+          make html
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: man/build/html
+      - id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/test-docs.yml

@@ -0,0 +1,31 @@
+name: Check documentation build
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  build-docs:
+    name: Build Sphinx docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          pip install -e .
+          pip install -r man/requirements.txt
+
+      - name: Regenerate autodocs and build
+        run: |
+          cd man
+          make update_autodocs
+          make html

README.md

@@ -4,7 +4,7 @@ A collection of tools to interact with [portable microhaplotype object (pmo) fil
 
 # Setup
 
-Install using pip
+Install using pip. Currently only supports python 3.11+
 ```bash
 pip install .
 ```
@@ -124,3 +124,23 @@ git add .
 git commit -m "Your message"
 git push origin feature/my-feature
 ```
+
+### Documentation updating
+
+Documentation for pmotools is automatically generated from docstring under `man/`. This is automatically built and deployed through GitHub actions on merging to main.
+
+You should check documentation before deployment. To update the documentation locally make sure you have pmotools-python installed.
+
+Next, from your development environment, install sphinx and its dependencies using the following command:
+
+```bash
+pip install -r man/requirements.txt
+```
+
+Build the documentation using the following commands
+```bash
+cd man
+make update_autodocs
+make html
+```
+You can open the html to review changes.