Add documentation build and deploy

.github/workflows/ci-xtgeoviz.yml

@@ -18,12 +18,11 @@ jobs:
   test:
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11"]
-        os: [ubuntu-latest]
-    runs-on: ${{ matrix.os }}
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+    runs-on: [ubuntu-latest]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
@@ -38,7 +37,34 @@ jobs:
       - name: Install
         run: |
           pip install -U pip
-          pip install ".[tests]"
+          pip install ".[tests,docs]"
 
       - name: Run tests
-        run: pytest -n auto --disable-warnings
+        run: pytest --disable-warnings
+
+      - name: Build documentation
+        if: ${{ always() }}
+        run: sphinx-build -b html docs build/docs/html
+
+      - name: Update GitHub pages
+        if: github.repository_owner == 'equinor' && github.ref == 'refs/heads/main' && matrix.python-version == '3.8'
+        run: |
+          cp -R ./build/docs/html ../html
+
+          git config --local user.email "xtgeoviz-github-action"
+          git config --local user.name "xtgeoviz-github-action"
+          git fetch origin gh-pages
+          git checkout --track origin/gh-pages
+          git clean -f -f -d -x  # Double -f is intentional
+          git rm -r *
+
+          cp -R ../html/* .
+          touch .nojekyll  # If not, github pages ignores _* directories.
+          git add .
+
+          if git diff-index --quiet HEAD; then
+            echo "No changes in documentation. Skip documentation deploy."
+          else
+            git commit -m "Update Github Pages"
+            git push "https://${{ github.actor }}:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git" gh-pages
+          fi

.github/workflows/linting.yml

@@ -19,10 +19,10 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.8", "3.12"]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
 

.github/workflows/xtgeoviz-publish-pypi.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
 

CONTRIBUTING.md

@@ -4,7 +4,8 @@ All contributions are welcome. You can contribute in many ways.
 
 ## Report Bugs
 
-Report bugs at https://github.com/equinor/xtgeoviz/issues.
+Report bugs at
+[https://github.com/equinor/xtgeoviz/issues](https://github.com/equinor/xtgeoviz/issues).
 When reporting a bug please include:
 
 - Your operating system name and version
@@ -32,7 +33,7 @@ official xtgeoviz documentation pages or in docstrings.
 ## Submit Feedback
 
 The best way to send feedback is to create an issue at
-https://github.com/equinor/xtgeoviz/issues.
+[https://github.com/equinor/xtgeoviz/issues](https://github.com/equinor/xtgeoviz/issues).
 
 If you are proposing a feature:
 
@@ -48,35 +49,35 @@ Ready to contribute? Here's how to set up `xtgeoviz` for local development.
 1. Fork this repository to your GitHub account
 2. Clone your fork locally:
    ```sh
-        git clone git@github.com:<your-user>/xtgeoviz.git
+    git clone git@github.com:<your-user>/xtgeoviz.git
     ```
 3. Install your local copy into a virtual environment:
     ```sh
-        python -m venv your-venv
-        source your-venv/bin/activate
-        cd xtgeoviz/
-        pip install ".[dev,docs]"
+    python -m venv your-venv
+    source your-venv/bin/activate
+    cd xtgeoviz/
+    pip install ".[dev,docs]"
     ```
 4. Create a feature branch for local development:
     ```sh
-        git checkout -b name-of-your-bugfix-or-feature
+    git checkout -b name-of-your-bugfix-or-feature
     ```
    Now you can make your changes locally.
 5. When you're done making changes, check that your changes pass flake8,
    black, isort, mypy, and the tests:
    ```sh
-       black src tests
-       isort src tests
-       flake8 src tests
-       mypy src
-       pytest
-    ```
+   black src tests
+   isort src tests
+   flake8 src tests
+   mypy src
+   pytest
+   ```
 6. Commit your changes and push your branch to GitHub:
    ```sh
-       git add your-changed file-names
-       git commit -m "Your detailed description of your changes."
-       git push origin name-of-your-bugfix-or-feature
-    ```
+   git add your-changed file-names
+   git commit -m "Your detailed description of your changes."
+   git push origin name-of-your-bugfix-or-feature
+   ```
 7. Create a pull request
 
 ## Pull Request Guidelines

README.md

@@ -1,23 +1,42 @@
 # xtgeoviz
 
-The intent is to replace xtgeo/plot functionality.
-
+[![tests](https://github.com/equinor/xtgeoviz/actions/workflows/ci-xtgeoviz.yml/badge.svg)](https://github.com/equinor/xtgeoviz/actions/workflows/ci-xtgeoviz.yml)
+![Python Version](https://img.shields.io/badge/python-3.8%20|%203.9%20|%203.10%20|%203.11%20|%203.12-blue.svg)
+[![License: LGPL v3](https://img.shields.io/github/license/equinor/fmu-tools)](https://www.gnu.org/licenses/lgpl-3.0)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![PyPI](https://img.shields.io/pypi/v/xtgeoviz.svg)](https://pypi.org/project/xtgeoviz/)
 
 Utility functions for plotting xtgeo objects.
 
+## Install
 
-# Usage
-
-Plan:
+xtgeoviz is available from PyPI.
 
+```sh
+pip install xtgeoviz
 ```
-import xtgeoviz.mpl as xtplot
+
+## Usage
+
+```python
+import xtgeoviz.plot as xtgplot
 import xtgeo
 
-```
 surf = xtgeo.surface_from_file("somemap.gri")
-xtplot.quickplot(surf)
+xtgplot.quickplot(surf)
 ```
 
+## Documentation
+
+The documentation can be found at
+[https://equinor.github.io/xtgeoviz](https://equinor.github.io/xtgeoviz).
+
+## Developing & Contributing
+
+All contributions are welcome. Please see the
+[Contributing document](https://equinor.github.io/xtgeoviz/contributing.html)
+for more details and instructions for getting started.
+
 ## License
-LGPL v3
+
+This software is released under the LGPLv3 license.

docs/conf.py

@@ -18,6 +18,7 @@
 release = xtgeoviz.__version__
 
 extensions = [
+    "myst_parser",
     "sphinxcontrib.apidoc",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",

docs/contributing.rst

@@ -0,0 +1,2 @@
+.. include:: ../CONTRIBUTING.md
+   :parser: myst_parser.sphinx_

docs/examples.rst

@@ -0,0 +1,4 @@
+Examples
+========
+
+Coming soon!

docs/index.rst

@@ -1,11 +1,12 @@
-Welcome to fmu-dataio' documentation!
-======================================
-
-Contents:
+Welcome to xtgeoviz' documentation
+==================================
 
 .. toctree::
    :maxdepth: 2
 
+   readme
+   examples
+   contributing
    apiref/modules
 
 Indices and tables

docs/readme.rst

@@ -0,0 +1,2 @@
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_

pyproject.toml

@@ -70,8 +70,9 @@ tests = [
     "types-PyYAML",
 ]
 docs = [
-    "sphinx",
     "autoapi",
+    "myst-parser",
+    "sphinx",
     "sphinxcontrib-apidoc",
     "sphinx-argparse",
     "sphinx-autodoc-typehints",