Add ci (#21)

* Fix formatting

* Add docs skeleton

* Add GitHub Actions workflows

* Use docs workflow for docs badge

---------

Co-authored-by: ElliottKasoar <ElliottKasoar@users.noreply.github.com>

.github/workflows/ci.yml

@@ -0,0 +1,75 @@
+name: ci
+
+on: [push, pull_request]
+
+jobs:
+
+  tests:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      matrix:
+        python-version: ['3.9','3.10','3.11','3.12']
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install poetry
+      run: pipx install poetry
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install python dependencies
+      run: |
+        poetry install --with dev
+
+    - name: Run test suite
+      env:
+        # show timings of tests
+        PYTEST_ADDOPTS: "--durations=0"
+      run: poetry run pytest --cov janus_core --cov-append .
+
+  docs:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install poetry
+      run: pipx install poetry
+
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v5
+      with:
+        python-version: 3.11
+
+    - name: Install python dependencies
+      run: poetry install --with docs
+
+    - name: Build docs
+      run: cd docs && poetry run make
+
+  pre-commit:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install poetry
+      run: pipx install poetry
+
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v5
+      with:
+        python-version: 3.11
+
+    - name: Install python dependencies
+      run: poetry install --with pre-commit,docs,dev
+
+    - name: Run pre-commit
+      run: |
+        poetry run pre-commit install
+        poetry run pre-commit run --all-files || ( git status --short ; git diff ; exit 1 )

.github/workflows/docs.yml

@@ -0,0 +1,52 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  docs-deploy:
+    if: github.ref == 'refs/heads/main'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    container: sphinxdoc/sphinx
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install poetry
+      run: |
+        apt update
+        apt upgrade -y
+        apt install -y pipx
+        pipx install poetry
+
+    - name: sphinx
+      run: |
+        export PATH="$HOME/.local/bin:$PATH"
+        poetry install --with docs
+        cd docs
+        poetry run make html
+
+    - name: upload
+      uses: actions/upload-pages-artifact@v3
+      with:
+        # Upload entire repository
+        path: './docs/build/html/.'
+
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

README.md

@@ -40,7 +40,7 @@ Contributors to this project were funded by
 [ci-link]: https://github.com/stfc/janus-core/actions
 [cov-badge]: https://coveralls.io/repos/github/stfc/janus-core/badge.svg?branch=main
 [cov-link]: https://coveralls.io/github/stfc/janus-core?branch=main
-[docs-badge]: https://github.com/stfc/janus-core/actions/workflows/pages/pages-build-deployment/badge.svg
+[docs-badge]: https://github.com/stfc/janus-core/actions/workflows/docs.yml/badge.svg
 [docs-link]: https://stfc.github.io/janus-core/
 [pypi-badge]: https://badge.fury.io/py/janus-core.svg
 [pypi-link]: https://badge.fury.io/py/janus-core

docs/Makefile

@@ -0,0 +1,41 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -n -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: all help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext customdefault
+
+## Runs nit-picky and converting warnings into errors to
+## make sure the documentation is properly written
+customdefault:
+	$(SPHINXBUILD) -b html -nW --keep-going $(ALLSPHINXOPTS) $(BUILDDIR)/html
+
+all: html
+
+clean:
+	rm -r $(BUILDDIR)
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+
+view:
+	xdg-open $(BUILDDIR)/html/index.html

docs/source/apidoc/janus_core.rst

@@ -0,0 +1,12 @@
+janus\_core package
+===================
+
+Module contents
+---------------
+
+.. automodule:: janus_core
+   :members:
+   :special-members:
+   :private-members:
+   :undoc-members:
+   :show-inheritance: