Merge pull request #102 from haddocking/mkdocs

Make mkdocs documentation for powerfit

Author: AnnaEngel98

.github/workflows/pages.yml

@@ -0,0 +1,70 @@
+name: Deploy MkDocs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+  pull_request:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Only have one deployment in progress at a time
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y openmpi-bin libopenmpi3 libopenmpi-dev
+
+      - name: install powerfit with extra dependencies
+        run: pip install '.[docs]'
+
+      - name: Build MkDocs site
+        run: |
+          mkdocs build
+        env:
+          # Force colored output from rich library
+          TTY_COMPATIBLE: "1"
+          TTY_INTERACTIVE: "0"
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    # Add a dependency to the build job
+    needs: build
+
+    # Only deploy on pushes to main or manual trigger of main branch
+    if: github.ref == 'refs/heads/main'
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    # Specify runner + deployment step
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing guidelines
 
-We welcome any kind of contribution to our software, from simple comment or question to a full fledged [pull request](https://help.github.com/articles/about-pull-requests/). Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md).
+We welcome any kind of contribution to our software, from simple comment or question to a full fledged [pull request](https://help.github.com/articles/about-pull-requests/). Please read and follow our [Code of Conduct](https://github.com/haddocking/powerfit/blob/master/CODE_OF_CONDUCT.md).
 
 A contribution can be one of the following cases:
 
@@ -31,7 +31,7 @@ The sections below outline the steps in each case.
 1. (**important**) announce your plan to the rest of the community *before you start working*. This announcement should be in the form of a (new) issue;
 1. (**important**) wait until some kind of consensus is reached about your idea being a good idea;
 1. if needed, fork the repository to your own Github profile and create your own feature branch off of the latest main commit. While working on your feature branch, make sure to stay up to date with the main branch by pulling in changes, possibly from the 'upstream' repository (follow the instructions [here](https://help.github.com/articles/configuring-a-remote-for-a-fork/) and [here](https://help.github.com/articles/syncing-a-fork/));
-1. install dependencies (see the [development documentation](README.md#development));
+1. install dependencies (see the [development documentation](#development));
 1. make sure the existing tests still work by running ``pytest``;
 1. add your own tests (if necessary);
 1. update or expand the documentation;
@@ -44,8 +44,8 @@ In case you feel like you've made a valuable contribution, but you don't know ho
 
 To create a release you need write permission on the repository.
 
-1. Check the author list in [`CITATION.cff`](CITATION.cff)
-1. Bump the version in [src/powerfit_em/__init__.py](src/powerfit_em/__init__.py)
+1. Check the author list in [`CITATION.cff`](https://github.com/haddocking/powerfit/blob/master/CITATION.cff)
+1. Bump the version in [src/powerfit_em/__init__.py](https://github.com/haddocking/powerfit/blob/master/src/powerfit_em/__init__.py)
 1. In [README.md](README.md) adjust docker command to use new version
 1. Go to the [GitHub release page](https://github.com/haddocking/powerfit/releases)
 1. Press draft a new release button
@@ -57,6 +57,30 @@ To create a release you need write permission on the repository.
 1. Wait until [Create and publish a Docker image](https://github.com/haddocking/powerfit/actions/workflows/docker-publish.yml) has completed.
 1. Verify [new Docker images](https://github.com/haddocking/powerfit/pkgs/container/powerfit)
 
+## Contributing to documentation
+
+Whenever you have changed something in the codebase, this also needs to be reflected in the documentation.
+To work on the PowerFit documentation you need to install the documentation version of using:
+
+```shell
+pip install -e .[docs]
+```
+
+Start the live-reloading docs server with:
+
+```shell
+mkdocs serve
+```
+
+Build the documentation site with:
+
+```shell
+mkdocs build
+# The site will be built in the 'site/' directory.
+# You can preview it with
+python3 -m http.server -d site
+```
+
 # Development
 
 To develop PowerFit, you need to install the development version of it using.