Various documentation updates and other updates

.github/workflows/build-and-test.yml

@@ -0,0 +1,81 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: Build and test
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_call:
+    outputs:
+      version:
+        description: "The version retrieved from the pyproject.toml file."
+        value: ${{ jobs.build-and-test.outputs.version }}
+
+jobs:
+  build-and-test:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10']
+    outputs:
+      version: ${{ steps.get_version.outputs.version }}
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    # Get the version from pyproject.toml
+    # This will be used to tag the release in the publishing workflow
+    - name: Install toml package
+      run: pip install toml
+    - name: Get version from pyproject.toml
+      id: get_version
+      run: |
+        VERSION=$(python -c "import toml; print(toml.load('pyproject.toml')['tool']['poetry']['version'])")
+        echo Version: $VERSION
+        echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+    # Installation
+    - name: Install dependencies
+      run: |
+        python -m pip install poetry
+        poetry install
+
+    # Testing and checking
+    - name: Test with pytest
+      run: |
+        poetry run pytest
+    - name: Type check
+      run: |
+        poetry run pytype .
+
+    # Build the package
+    - name: Build the package
+      run: |
+        poetry build
+    - name: Archive build artifacts
+      uses: actions/upload-artifact@v4
+      if: github.ref == 'refs/heads/release'
+      with:
+        name: build-artifacts
+        path: dist/
+
+    # Build the docs
+    - name: Build the docs
+      run: |
+        poetry run make html --directory docs
+    - name: Archive documentation
+      uses: actions/upload-artifact@v4
+      if: github.ref == 'refs/heads/release'
+      with:
+        name: docs-html
+        path: docs/build/html/

.github/workflows/publish.yml

@@ -0,0 +1,115 @@
+# Sources:
+# https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/#workflow-definition
+# https://github.com/marketplace/actions/pypi-publish
+
+name: Publish package and docs
+
+on:
+  push:
+    branches: [ release ]
+
+jobs:
+  build-and-test:
+    uses: ./.github/workflows/build-and-test.yml
+
+  create-tag:
+    name: Create Git Tag
+    needs: build-and-test
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Create Git Tag
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        VERSION: ${{ needs.build-and-test.outputs.version }}
+      run: |
+        git config --global user.name 'github-actions'
+        git config --global user.email '[email protected]'
+        git tag "v${VERSION}"
+        git push origin "v${VERSION}"
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: [build-and-test, create-tag]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/tsdf
+    permissions:
+      id-token: write  # mandatory for trusted publishing
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: build-artifacts
+        path: dist/
+    - name: Publish distribution 📦 to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+
+
+  github-release:
+    name: Sign distribution and create GitHub release
+    needs: [build-and-test, create-tag]
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write  # mandatory for making GitHub Releases
+      id-token: write  # mandatory for sigstore
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: build-artifacts
+        path: dist/
+
+    - name: Sign the dists with Sigstore
+      uses: sigstore/[email protected]
+      with:
+        inputs: >-
+          ./dist/*.tar.gz
+          ./dist/*.whl
+
+    - name: Create GitHub Release
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+        VERSION: ${{ needs.build-and-test.outputs.version }}
+      run: >-
+        gh release create
+        "v${VERSION}"
+        --repo '${{ github.repository }}'
+        --notes ""
+
+    - name: Upload artifact signatures to GitHub Release
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+        VERSION: ${{ needs.build-and-test.outputs.version }}
+      # Upload to GitHub Release using the `gh` CLI.
+      # `dist/` contains the built packages, and the
+      # sigstore-produced signatures and certificates.
+      run: >-
+        gh release upload
+        "v${VERSION}" dist/**
+        --repo '${{ github.repository }}'
+
+
+  publish-docs:
+    name: Publish documentation
+    needs: build-and-test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download the documentation
+        uses: actions/download-artifact@v4
+        with:
+          name: docs-html
+          path: docs/
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/

.gitignore

@@ -69,7 +69,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+docs/build/
 
 # PyBuilder
 target/

README.md

@@ -4,7 +4,7 @@
 | Badges | |
 |:----:|----|
 | **Packages and Releases** | [![Latest release](https://img.shields.io/github/release/biomarkersparkinson/tsdf.svg)](https://github.com/biomarkersparkinson/tsdf/releases/latest) [![PyPI](https://img.shields.io/pypi/v/tsdf.svg)](https://pypi.python.org/pypi/tsdf/)  [![Static Badge](https://img.shields.io/badge/RSD-tsdf-lib)](https://research-software-directory.org/software/tsdf) |
-| **Build Status** | [![](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/) ![Python package](https://github.com/biomarkersparkinson/tsdf/workflows/Python%20package/badge.svg) [![pytype Type Check](https://github.com/biomarkersParkinson/tsdf/actions/workflows/pytype-checking.yml/badge.svg)](https://github.com/biomarkersParkinson/tsdf/actions/workflows/pytype-checking.yml) |
+| **Build Status** | [![](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/) ![Python package](https://github.com/biomarkersparkinson/tsdf/workflows/Python%20package/badge.svg) [![pytype Type Check](https://github.com/biomarkersParkinson/tsdf/actions/workflows/pytype-checking.yml/badge.svg)](https://github.com/biomarkersParkinson/tsdf/actions/workflows/pytype-checking.yml) |
 | **DOI** | [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7867899.svg)](https://doi.org/10.5281/zenodo.7867899) |
 | **License** |  [![GitHub license](https://img.shields.io/github/license/biomarkersParkinson/tsdf)](https://github.com/biomarkersparkinson/tsdf/blob/main/LICENSE) |
 | **Fairness** |  [![fair-software.eu](https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F-green)](https://fair-software.eu) [![OpenSSF Best Practices](https://bestpractices.coreinfrastructure.org/projects/8083/badge)](https://www.bestpractices.dev/projects/8083) |
@@ -17,7 +17,7 @@ A package ([documentation](https://biomarkersparkinson.github.io/tsdf/)) to load
 
 ### Using `pip`
 
-The package is available in PyPi and requires [Python 3.9](https://www.python.org/downloads/) or higher. It can be installed using:
+The package is available in PyPi and requires [Python 3.10](https://www.python.org/downloads/) or higher. It can be installed using:
 
 ```bash
 $ pip install tsdf
@@ -38,12 +38,10 @@ poetry run pytest
 
 ### Building the documentation
 
-We use [mkdocs](https://www.mkdocs.org/) to build the documentation. If you want to build the documentation locally, the following commands will prove useful:
+We use [Sphinx](https://www.sphinx-doc.org/) to build the documentation. Use this command to build the documentation locally:
 
 ```bash
-mkdocs build       # build the documentation
-mkdocs serve       # serve the documentation on a local server
-mkdocs gh-deploy   # deploy the documentation to GitHub pages
+poetry run make html --directory docs
 ```
 
 ## Contributing

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/basic_reading_and_writing_numpy.ipynb

@@ -22,11 +22,10 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Load some data"
+    "## Load some data"
    ]
   },
   {
@@ -68,7 +67,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Perform basic data processing"
+    "## Perform basic data processing"
    ]
   },
   {
@@ -99,7 +98,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Write the processed data \n",
+    "## Write the processed data \n",
     "Write the processed data in binary format. The call returns the corresponding metadata object."
    ]
   },
@@ -136,7 +135,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Write the TSDF metadata file"
+    "## Write the TSDF metadata file"
    ]
   },
   {
@@ -164,7 +163,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Write a metadata file that combines multiple binary files"
+    "## Write a metadata file that combines multiple binary files"
    ]
   },
   {