Merge pull request #55 from neutrons/mkdocs

Migrate to mkdocs

.github/dependabot.yml

@@ -0,0 +1,10 @@
+# Set update schedule for GitHub Actions
+
+version: 2
+updates:
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      # Check for updates to GitHub Actions every week
+      interval: "monthly"

.github/pull_request_template.md

@@ -23,4 +23,3 @@ Check all that apply:
 - [ ] All the tests are passing
 - [ ] The documentation is up to date
 - [ ] code comments added when explaining intent
-

.github/workflows/actions.yml

@@ -14,20 +14,23 @@ jobs:
       run:
         shell: bash -l {0}
     steps:
-    - uses: actions/checkout@v2
-    - name: Set up Miniconda
-      uses: conda-incubator/setup-miniconda@v2
-      with:
-        auto-update-conda: true
-        miniforge-version: latest
-        environment-file: environment.yml
-    - name: Test with pytest
-      working-directory: ./reduction
-      run: |
-        git submodule add --force https://code.ornl.gov/sns-hfir-scse/infrastructure/test-data/liquidsreflectometer-data.git tests/data/liquidsreflectometer-data
-        git submodule update --init
-        python -m pytest -vv --cov=. --cov-report=xml --cov-report=term test
-    - name: Upload coverage reports to Codecov
-      uses: codecov/codecov-action@v3
-      env:
-        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+      - uses: actions/checkout@v4
+
+      - name: Set up Miniconda
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          auto-update-conda: true
+          miniforge-version: latest
+          environment-file: environment.yml
+
+      - name: Test with pytest
+        working-directory: ./reduction
+        run: |
+          git submodule add --force https://code.ornl.gov/sns-hfir-scse/infrastructure/test-data/liquidsreflectometer-data.git tests/data/liquidsreflectometer-data
+          git submodule update --init
+          python -m pytest -vv --cov=. --cov-report=xml --cov-report=term test
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v3
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/deploy_docs.yaml

@@ -0,0 +1,38 @@
+name: Build and Deploy Docs to GitHub Pages
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - master
+
+env:
+  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # otherwise, you will failed to push refs to dest repo
+
+      - name: Set up Miniconda
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          auto-update-conda: true
+          miniforge-version: latest
+          environment-file: environment.yml
+
+      - name: Install Dependencies
+        run: pip install .[dev]
+
+      - name: Build Documentation
+        run: make docs
+
+      - name: Deploy to gh-pages
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: site
+          target-folder: docs
+          clean: true

.pre-commit-config.yaml

@@ -4,16 +4,20 @@
 exclude: '(reduction/data|reduction/notebooks|scripts|scans)/.*'
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v4.4.0
+  rev: v5.0.0
   hooks:
     - id: check-added-large-files
       args: [--maxkb=4096]
     - id: check-merge-conflict
     - id: end-of-file-fixer
     - id: trailing-whitespace
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.0.278
+  rev: v0.8.3
   hooks:
     - id: ruff
       args: [--fix, --exit-non-zero-on-fix]
       types_or: [python, pyi, jupyter]
+
+ci:
+  autoupdate_schedule: monthly
+  skip: [eslint]

Makefile

@@ -10,12 +10,12 @@ SHELL=/bin/bash
 .PHONY: help conda docs test install
 
 help:
-    # this nifty perl one-liner collects all commnents headed by the double "#" symbols next to each target and recycles them as comments
+    # This nifty perl one-liner collects all commnents headed by the double "#" symbols next to each target and recycles them as comments
 	@perl -nle'print $& if m{^[a-zA-Z_-]+:.*?## .*$$}' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-25s\033[0m %s\n", $$1, $$2}'
 
 
 PREFIX := /SNS/REF_L/shared
-install:  ## install the automated reduction code for LR
+install:  ## Install the automated reduction code for LR
 	versioningit -w
 	cp -R scripts/livereduce/*.py $(PREFIX)/livereduce
 	cp -R scripts/autoreduce/*.py $(PREFIX)/autoreduce
@@ -32,9 +32,8 @@ conda-env:  ## creates conda environment `lr_reduction` and installs package `lr
 	$(CONDA_ACTIVATE) lr_reduction
 	pip install -e .
 
-docs:  ## generates HTML docs under `docs/_build/html/`, treating warnings as errors. Requires activation of the `lr_reduction` conda environment
-	# this will fail on a warning
-	@cd docs&& make html SPHINXOPTS="-W --keep-going -n" && echo -e "##########\n DOCS point your browser to file://$$(pwd)/build/html/index.html\n##########"
+docs: ## Build the documentation
+	mkdocs build
 
-test-all:  ## run all tests
+test-all:  ## Run all tests
 	pytest ./test

docs/api/background.md

@@ -0,0 +1 @@
+::: lr_reduction.background

docs/api/event_reduction.md

@@ -0,0 +1 @@
+::: lr_reduction.event_reduction

docs/api/index.md

@@ -0,0 +1,11 @@
+# Overview
+
+- [lr_reduction.background](./background.md)
+- [lr_reduction.event_reduction](./event_reduction.md)
+- [lr_reduction.output](./output.md)
+- [lr_reduction.peak_finding](./peak_finding.md)
+- [lr_reduction.reduction_template_reader](./reduction_template_reader.md)
+- [lr_reduction.template](./template.md)
+- [lr_reduction.time_resolved](./time_resolved.md)
+- [lr_reduction.utils](./utils.md)
+- [lr_reduction.workflow](./workflow.md)

docs/api/output.md

@@ -0,0 +1 @@
+::: lr_reduction.output

docs/api/peak_finding.md

@@ -0,0 +1 @@
+::: lr_reduction.peak_finding

docs/api/reduction_template_reader.md

@@ -0,0 +1 @@
+::: lr_reduction.reduction_template_reader

docs/api/template.md

@@ -0,0 +1 @@
+::: lr_reduction.template

docs/api/time_resolved.md

@@ -0,0 +1 @@
+::: lr_reduction.time_resolved

docs/api/utils.md

@@ -0,0 +1 @@
+::: lr_reduction.utils

docs/api/workflow.md

@@ -0,0 +1 @@
+::: lr_reduction.workflow