Merge pull request #14 from xarray-contrib/docs_update

Adjust docs build

Author: melonora

.github/workflows/test_docs.yml

@@ -0,0 +1,21 @@
+name: Test documentation build
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: prefix-dev/[email protected]
+        with:
+          pixi-version: v0.49.0
+          frozen: true
+      - name: Test build documentation
+        run: |
+          pixi run -e dev doc_build

CITATION.cff

@@ -1,15 +1,19 @@
 cff-version: 1.2.0
 message: "If you use this software, please cite it as below."
 
-title: "xarray-dataclasses"
+title: "xarray-dataclass"
 abstract: "xarray data creation by data classes"
 version: 1.9.1
 date-released: 2024-12-09
 license: "MIT"
 doi: "10.5281/zenodo.4624819"
-url: "https://github.com/astropenguin/xarray-dataclasses"
+url: "https://github.com/xarray-contrib/xarray-dataclass"
 authors:
   - given-names: "Akio"
     family-names: "Taniguchi"
     affiliation: "Nagoya University"
     orcid: "https://orcid.org/0000-0002-9695-6183"
+  - given-names: "Wouter-Michiel Vierdag"
+    family-names: "Vierdag"
+    affiliation: "European Molecular Biology Laboratory"
+    orcid: "https://orcid.org/0000-0003-1666-5421"

README.md

@@ -67,7 +67,7 @@ pixi add --pypi xarray-dataclasses
 
 ## Basic usage
 
-xarray-dataclasses uses [the Python's dataclass].
+xarray-dataclass uses [the Python's dataclass].
 Data (or data variables), coordinates, attributes, and a name of DataArray or Dataset objects will be defined as dataclass fields by special type hints (`Data`, `Coord`, `Attr`, `Name`), respectively.
 Note that the following code is supposed in the examples below.
 
@@ -378,25 +378,24 @@ pixi run pre-commit-install
 ```
 
 ### Testing, linting, and formatting
-We have [a test workflow][test-workflow] for testing, static type checking, linting, and formatting the code.
-It is used for status checks when a pull request is created.
-If you would like to check them in local, the following commands are almost equivalent (the difference is that the workflow is run under multiple Python versions).
+We have a test workflow for testing and a pre-commit workflow for static type checking, linting, and formatting the code.
+It is performed when a pull request is created against main.
+If you would like to check them in local, the following commands are almost equivalent (the difference is that the test workflows are run under multiple Python versions).
 Furthermore, these tasks are defined only in the `dev` environment. Pixi does not require you to specify the environment
 in that case.
 
-```shell
+```
 pixi run tests
-pixi run flake8
-pixi run black
-pixi run pyright
+pixi run -e dev pre-commit run --all-files
 ```
 
 ### Creating documentation
-We also have a [documentation workflow] (Add link). However, if you want to locally create the documentation
+We also have a documentation workflow. However, if you want to locally create the documentation
 run the following:
 
 ```shell
-pixi run doc_build
+pixi run doc_build # this just creates the build
+pixi run doc_serve # build and serve at http://localhost:8000/
 ```
 
 ### Create a release

docs/_templates/layout.html

@@ -0,0 +1,23 @@
+{# Extend the theme's layout #}
+{% extends "!layout.html" %}
+
+{# Add custom elements to the page #}
+{% block extrahead %}
+  {{ super() }}
+  <meta name="docsearch:version" content="{{ version }}">
+{% endblock %}
+
+{# Add version information for the current page #}
+{% block footer %}
+  {{ super() }}
+  <script>
+    // Add version information to the current page
+    document.addEventListener('DOMContentLoaded', function() {
+      // This helps search engines and other tools understand the version of the page
+      var meta = document.createElement('meta');
+      meta.name = 'version';
+      meta.content = '{{ version }}';
+      document.head.appendChild(meta);
+    });
+  </script>
+{% endblock %}

docs/conf.py

@@ -1,6 +1,12 @@
+from datetime import datetime
+
+# Get current year for copyright
+current_year = datetime.now().year
+
 # project information
-author = "Akio Taniguchi"
-copyright = "2020-2024 Akio Taniguchi"
+project = "xarray-dataclass"
+author = "Wouter-Michiel Vierdag"
+copyright = f"{current_year} Wouter-Michiel Vierdag"
 
 
 # general configuration
@@ -31,6 +37,17 @@
         "image_light": "logo-light.svg",
         "image_dark": "logo-dark.svg",
     },
-    "github_url": "https://github.com/astropenguin/xarray-dataclasses/",
-    "twitter_url": "https://twitter.com/astropengu_in/",
+    "github_url": "https://github.com/xarray-contrib/xarray-dataclass/",
+    "twitter_url": "https://x.com/xarray_dev/",
+    "show_prev_next": False,
+    "icon_links": [
+        {
+            "name": "PyPI",
+            "url": "https://pypi.org/project/xarray-dataclass/",
+            "icon": "fa-solid fa-box",
+        },
+    ],
+    "external_links": [
+        {"name": "xarray", "url": "https://xarray.pydata.org/"},
+    ],
 }

pixi.lock

@@ -10,6 +10,9 @@ authors = [
     {name = "Akio Taniguchi", email = "[email protected]"},
     {name = "Wouter-Michiel Vierdag", email = "[email protected]"}
 ]
+maintainers = [
+  {name = "Wouter-Michiel Vierdag", email = "[email protected]"}
+]
 readme = "README.md"
 license.file = "LICENSE"
 
@@ -71,6 +74,7 @@ dev = { features = ["dev"], solve-group = "default" }
 [tool.pixi.feature.dev.tasks]
 tests = "pytest"
 doc_build = { cmd = "sphinx-apidoc -efT -o docs/_apidoc src/xarray_dataclasses && sphinx-build -a docs docs/_build" }
+doc_serve = { cmd = "sphinx-build -a docs docs/_build && python -m http.server --directory docs/_build 8000" }
 
 [tool.pyright]
 reportMissingImports = "none"