Merge pull request #90 from StagPython/mkdocs

Migrate documentation to mkdocs

Author: amorison

.github/workflows/docs.yml

@@ -0,0 +1,44 @@
+name: docs
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+  pull_request:
+    branches:
+      - master
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: '0'
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+      - run: python3 -m pip install -U pip
+      - run: python3 -m pip install -r docs/requirements.txt
+      - run: python3 -m pip install .
+      - run: mkdocs build
+        env:
+          STAGPY_DOC_CONFIG: 1
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: "site/"
+
+  deploy:
+    needs: build
+    if: github.ref == 'refs/heads/master'
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/deploy-pages@v4
+        id: deployment

.gitignore

@@ -7,7 +7,3 @@ stagpy.egg-info/
 /build/
 /stagpy/_version.py
 /stagpy_git/
-docs/_build/
-docs/_static/
-docs/_templates/
-docs/sources/config_opts.rst

.readthedocs.yml

@@ -0,0 +1,25 @@
+[![PyPI - Version](https://img.shields.io/pypi/v/stagpy)](https://pypi.org/project/stagpy/)
+[![DOI on zenodo](https://zenodo.org/badge/DOI/10.5281/zenodo.5512348.svg)](https://doi.org/10.5281/zenodo.5512348)
+
+StagPy
+======
+
+StagPy is a command line tool to process the output files of your StagYY
+simulations and produce high-quality figures.
+
+This command line tool is built around a generic interface that allows you to
+access StagYY output data directly in a Python script.
+
+You can install StagPy with `pip` from the [Python Package
+Index](https://pypi.org/project/stagpy/).
+
+If StagPy has been useful to your research, please consider citing the project
+as:
+
+> Adrien Morison, Martina Ulvrova, Stephane Labrosse, & contributors. (2021).
+StagPython/StagPy. Zenodo. https://doi.org/10.5281/zenodo.5512348
+
+or a specific version with the relevant DOI (e.g. for v0.15.0):
+
+> Adrien Morison, Martina Ulvrova, Stephane Labrosse, & contributors. (2021).
+StagPython/StagPy (v0.15.0). Zenodo. https://doi.org/10.5281/zenodo.5512349

README.md

@@ -2,59 +2,59 @@ Snapshots using command line
 ============================
 
 For the examples here, simply copy and paste the command line in your
-shell, working in the directory where the StagYY par file is located. 
+shell, working in the directory where the StagYY par file is located.
 You can also use the examples on the data available in the Examples
-directory. 
+directory.
 
 The next use of stagpy is to create images of snapshots of the
 different fields.
 
-::
-
-   % stagpy field -o T
+```sh title="shell"
+stagpy field -o T
+```
 
 will plot the last snapshot of the temperature field.
 
-::
-
-    % stagpy field -s : -o T-v3
+```sh title="shell"
+stagpy field -s : -o T-v3
+```
 
 will plot all the snapshots of the temperature and the vertical/radial velocity
 on separate figures.
 
-::
-
-    % stagpy field -s 3:8:2 -o T,stream
+```sh title="shell"
+stagpy field -s 3:8:2 -o T,stream
+```
 
 will plot the temperature field with isocontours of the stream function from
 the third to the eighth snapshot, every two snapshots.
 
-::
+```sh title="shell"
+stagpy field -o T -s 1,5 --vmin=0.8 --vmax=1.0
+```
 
-    % stagpy field -o T -s 1,5 --vmin=0.8 --vmax=1.0
-   
 will plot the temperature field from the first and the fifth snapshot while
 keeping the range of the colorbar fixed between 0.8 and 1.
 
 List of variables to plot
 -------------------------
 
-The list of fields specified with the ``-o`` (or ``--plot``) option follows the
-same rules as for the ``rprof`` and ``time`` subcommands.  Namely,
-``,``-separated variables are on the same subplots; ``.``-separated variables
-are on the same figure but different subplots; ``-``-separated variables are
+The list of fields specified with the `-o` (or `--plot`) option follows the
+same rules as for the `rprof` and `time` subcommands.  Namely,
+`,`-separated variables are on the same subplots; `.`-separated variables
+are on the same figure but different subplots; `-`-separated variables are
 on different figures.
 
 Note that only two fields can be on the same subplot, the first field is a
 color map and the second field can be either:
 
 - a scalar field, isocontours are added to the plot;
-- a vector field (e.g. ``v`` for the ``(v1, v2, v3)`` vector), arrows are added
+- a vector field (e.g. `v` for the `(v1, v2, v3)` vector), arrows are added
   to the plot.
 
-For example, ``-o=T,v3`` asks for a temperature map with isocontour of the
-vertical velocity, while ``-o=T,v`` asks for a temperature map with velocity
+For example, `-o=T,v3` asks for a temperature map with isocontour of the
+vertical velocity, while `-o=T,v` asks for a temperature map with velocity
 vectors on top of it.
 
 If you ask for more than two fields on the same subplot, extra fields are
-ignored.  ``-o=T,stream,v`` is therefore equivalent to ``-o=T,stream``.
+ignored. `-o=T,stream,v` is therefore equivalent to `-o=T,stream`.