Merge pull request #80 from biomarkersParkinson/migrate-documentation

Use Sphinx for documentation instead of mkdocs

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

@@ -0,0 +1,64 @@
+# 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.9']
+    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
+    - 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
+
+    - name: Install dependencies
+      run: |
+        python -m pip install poetry
+        poetry install
+    - name: Build the docs  # just to see whether the build passes
+      run: |
+        poetry run make html --directory docs
+    - name: Test with pytest
+      run: |
+        poetry run pytest
+    # TODO: run pytype here?
+    - name: Build the package
+      run: |
+        poetry build
+    - name: Archive build artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: build-artifacts
+        path: dist/

README.md

@@ -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"
    ]
   },
   {

docs/basic_reading_and_writing_pandas.ipynb

@@ -25,7 +25,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Load some data"
+    "## Load some data"
    ]
   },
   {
@@ -166,7 +166,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Perform basic data processing"
+    "## Perform basic data processing"
    ]
   },
   {
@@ -306,7 +306,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 updates the metadata object with the data attributes of the dataframe."
    ]
   },
@@ -339,7 +339,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Write the TSDF metadata file"
+    "## Write the TSDF metadata file"
    ]
   },
   {

docs/conf.py

@@ -0,0 +1,58 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'tsdf'
+copyright = '2024, Netherlands eScience Center'
+author = 'Netherlands eScience Center'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+
+# General configuration
+extensions = [
+    "myst_nb",
+    "autoapi.extension",
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+]
+autoapi_dirs = ['../src']
+autoapi_add_toctree_entry = False
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# Options for HTML output
+html_theme = 'sphinx_rtd_theme'
+html_theme_options = {
+    'canonical_url': 'https://biomarkersparkinson.github.io/tsdf/',
+}
+
+html_static_path = ['_static']
+
+# Keep the main TOC always visible
+html_sidebars = {
+    '**': [
+        'globaltoc.html',  # Add this line
+        'relations.html',  # needs 'show_related': True theme option to display
+        'sourcelink.html',
+        'searchbox.html',
+    ]
+}
+
+# Repository settings
+html_context = {
+    "display_github": True,  # Integrate GitHub
+    "github_user": "biomarkersParkinson",  # Username
+    "github_repo": "tsdf",  # Repo name
+    "github_version": "main",  # Version
+    "conf_py_path": "/docs/",  # Path in the checkout to the docs root
+}
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

docs/converting_legacy_data.ipynb

@@ -4,8 +4,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Transform legacy (TSDB) format to the current TSDF v0.1\n",
-    "Transform one file (or all files within the given directory) from TSDB to TSDF format."
+    "# Transform legacy format\n",
+    "\n",
+    "Transform one file (or all files within the given directory) from legacy TSDB to the current TSDF format (v0.1)."
    ]
   },
   {

docs/index.rst

@@ -0,0 +1,35 @@
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Getting Started
+
+   introduction
+   installation
+
+.. toctree::
+   :maxdepth: 2
+   :caption: The format
+
+   tsdf_fields_table
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Usage
+
+   basic_reading_and_writing_numpy
+   basic_reading_and_writing_pandas
+   writing_data_from_scratch
+   converting_legacy_data
+   validating_files
+
+.. toctree::
+   :maxdepth: 2
+   :caption: API Reference
+
+   autoapi/tsdf/index
+
+.. toctree::
+   :maxdepth: 2
+   :caption: About
+
+   contact

docs/installation.md

@@ -25,4 +25,4 @@ Otherwise you can install it manually by following these steps:
 ## What now?
 
 Now you can import functions from the `tsdf` Python package.
-See some examples in the [usage section](/tsdf/basic_reading_and_writing_numpy).
+See some examples in the [usage section](/basic_reading_and_writing_numpy).

docs/index.md → docs/introduction.md

@@ -1,4 +1,6 @@
-# Welcome to the TSDF (Time Series Data Format) Python package
+# Introduction
+
+Welcome to the TSDF (Time Series Data Format) Python package!
 
 A package to work with TSDF data in Python. This implementation is based on the the TSDF format specification, which can be found in this [preprint](https://arxiv.org/abs/2211.11294).
 

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,3 @@
+myst-nb
+sphinx-autoapi
+sphinx-rtd-theme

docs/validating_files.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Validate TSDF file\n",
+    "# Validate TSDF file\n",
     "\n",
     "Files can be validated using the validator module, which is also callable from the command line. The validator checks the metadata file and inspects whether the binary file is consistent with the metadata.\n",
     "\n",