add gh-action

Author: stefantaubert

.github/workflows/documentation.yml

@@ -0,0 +1,46 @@
+name: documentation
+
+on:
+  push:
+    branches: ["main"]
+
+  pull_request:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    env:
+      IS_GITHUB_RUNNER: "true"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Upgrade pip
+        run: python -m pip install --upgrade pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install uv --upgrade
+          python -m uv pip install --system .[docs]
+
+      - name: Sphinx build
+        run: |
+          sphinx-build -b html docs/ docs/_build/html -j auto
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./_build/html
+          # force_orphan: true

docs/changelog.rst

@@ -0,0 +1,2 @@
+.. include:: ../CHANGELOG.md
+   :parser: myst

docs/conf.py

@@ -18,6 +18,7 @@
   "sphinx.ext.autodoc",
   "sphinx_autodoc_typehints",
   "numpydoc",
+  "myst_parser",
 ]
 
 templates_path = ["_templates"]

docs/index.rst

@@ -14,17 +14,18 @@ Documentation for the birdnet package.
 
    birdnet
    models
+   changelog
 
 Introduction
 ------------
 
 A Python library for identifying bird species by their sounds.
 
-The library is geared towards providing a robust workflow for ecological data analysis in bioacoustic projects. While it covers essential functionalities, it doesn’t include all the features found in BirdNET-Analyzer, which is available [here](https://github.com/birdnet-team/BirdNET-Analyzer). Some features might only be available in the BirdNET Analyzer and not in this package.
+The library is geared towards providing a robust workflow for ecological data analysis in bioacoustic projects. While it covers essential functionalities, it doesn’t include all the features found in BirdNET-Analyzer, which is available `here <https://github.com/birdnet-team/BirdNET-Analyzer>`__. Some features might only be available in the BirdNET Analyzer and not in this package.
 
 This project is under active development, so you might encounter changes that could affect your current workflow. We recommend checking for updates regularly.
 
-The package is also available as an R package at: [birdnetR](https://github.com/birdnet-team/birdnetR).
+The package is also available as an R package at: `birdnetR <https://github.com/birdnet-team/birdnetR>`__.
 
 Citing BirdNET-Analyzer
 -----------------------
@@ -46,37 +47,37 @@ Feel free to use BirdNET for your acoustic analyses and research. If you do, ple
 About
 -----
 
-Developed by the `K. Lisa Yang Center for Conservation Bioacoustics <https://www.birds.cornell.edu/ccb/>`_ at the `Cornell Lab of Ornithology <https://www.birds.cornell.edu/home>`_ in collaboration with `Chemnitz University of Technology <https://www.tu-chemnitz.de/index.html>`_.
+Developed by the `K. Lisa Yang Center for Conservation Bioacoustics <https://www.birds.cornell.edu/ccb/>`__ at the `Cornell Lab of Ornithology <https://www.birds.cornell.edu/home>`__ in collaboration with `Chemnitz University of Technology <https://www.tu-chemnitz.de/index.html.en>`__.
 
 Go to https://birdnet.cornell.edu to learn more about the project.
 
 Want to use BirdNET to analyze a large dataset? Don't hesitate to contact us: ccb-birdnet@cornell.edu
 
-We also have a discussion forum on `Reddit <https://www.reddit.com/r/BirdNET_Analyzer/>`_ if you have a general question or just want to chat.
+We also have a discussion forum on `Reddit <https://www.reddit.com/r/BirdNET_Analyzer/>`__ if you have a general question or just want to chat.
 
 Have a question, remark, or feature request? Please start a new issue thread to let us know. Feel free to submit a pull request.
 
 More tools and resources
 ------------------------
 
-We also provide Python and R packages to interact with BirdNET models, as well as training and deployment tools for microcontrollers. Make sure to check out our other repositories at `https://github.com/birdnet-team <https://github.com/birdnet-team>`_.
+We also provide Python and R packages to interact with BirdNET models, as well as training and deployment tools for microcontrollers. Make sure to check out our other repositories at `https://github.com/birdnet-team <https://github.com/birdnet-team>`__.
 
 
 Projects map
 ------------
 
 We have created an interactive map of projects that use BirdNET. If you are working on a project that uses BirdNET, please let us know and we can add your project to the map.
 
-You can access the map here: `Open projects map <https://birdnet-team.github.io/BirdNET-Analyzer/projects.html>`_
+You can access the map here: `Open projects map <https://birdnet-team.github.io/BirdNET-Analyzer/projects.html>`__
 
-Please refer to the `projects map documentation <usage/projects-map.html>`_ for more information on how to contribute.
+Please refer to the `projects map documentation <usage/projects-map.html>`__ for more information on how to contribute.
 
 License
 -------
 
-**Source Code**: The source code for this project is licensed under the `MIT License <https://opensource.org/licenses/MIT>`_
+**Source Code**: The source code for this project is licensed under the `MIT License <https://opensource.org/licenses/MIT>`__
 
-**Models**: The models used in this project are licensed under the `Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (CC BY-NC-SA 4.0) <https://creativecommons.org/licenses/by-nc-sa/4.0/>`_
+**Models**: The models used in this project are licensed under the `Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (CC BY-NC-SA 4.0) <https://creativecommons.org/licenses/by-nc-sa/4.0/>`__
 
 Please ensure you review and adhere to the specific license terms provided with each model.
 

docs/models.rst

@@ -25,19 +25,19 @@ Technical details
 
 * both spectrograms have a final resolution of 96x511 pixels
 * raw audio will be normalized between -1 and 1 before spectrogram conversion
-* we use non-linear magnitude scaling as mentioned in `Schlüter 2018 <http://ceur-ws.org/Vol-2125/paper_181.pdf>`_
+* we use non-linear magnitude scaling as mentioned in `Schlüter 2018 <http://ceur-ws.org/Vol-2125/paper_181.pdf>`__
 * V2.4 uses an EfficienNetB0-like backbone with a final embedding size of 1024
-* See `this comment <https://github.com/birdnet-team/BirdNET-Analyzer/issues/177#issuecomment-1772538736>`_ for more details
+* See `this comment <https://github.com/birdnet-team/BirdNET-Analyzer/issues/177#issuecomment-1772538736>`__ for more details
 
 Geo model (species range model) V2.4 - V2, Jan 2024
 ---------------------------------------
 
 * updated species range model based on eBird data
 * more accurate (spatial) species range prediction
 * slightly increased long-tail distribution in the temporal resolution 
-* see `this discussion post <https://github.com/birdnet-team/BirdNET-Analyzer/discussions/234>`_ for more details
+* see `this discussion post <https://github.com/birdnet-team/BirdNET-Analyzer/discussions/234>`__ for more details
 
 Using older models
 ------------------
 
-Older models are not supported in the current version of the package. If you need to use an older model, please refer to the `BirdNET-Analyzer repository <https://github.com/birdnet-team/BirdNET-Analyzer>`_.
+Older models are not supported in the current version of the package. If you need to use an older model, please refer to the `BirdNET-Analyzer repository <https://github.com/birdnet-team/BirdNET-Analyzer>`__.

pyproject.toml

@@ -118,6 +118,7 @@ tests = [
   "ruff >= 0.14.4"
 ]
 dev = ["jupyter", "uv", "ruff", "mypy", "rope", "build", "twine", "scipy-stubs", "tuna", "pyarrow-stubs", "types-tqdm", "types-requests", "pandas-stubs", "types-tensorflow"]
+docs = ["sphinx==9.0.4", "numpydoc", "sphinx-autodoc-typehints", "sphinx-autobuild", "myst-parser"]
 
 [project.urls]
 Homepage = "https://github.com/birdnet-team/birdnet"

src/birdnet/model_loader.py

@@ -1,3 +1,7 @@
+"""Module for loading models.
+Provides functions to load official and custom models.
+"""
+
 from os import PathLike
 from pathlib import Path
 from typing import Any, Literal, cast