Merge pull request #573 from kahst:extend-docs

Extend docs
kahst · Feb 12, 2025 · 7fa4d53 · 7fa4d53
2 parents 9b8b499 + 270da87
commit 7fa4d53
Show file tree

Hide file tree

Showing 11 changed files with 164 additions and 91 deletions.
diff --git a/README.md b/README.md
@@ -12,6 +12,7 @@
 [![Python 3.11](https://img.shields.io/badge/python-3.11-blue.svg)](https://www.python.org/downloads/release/python-3110/)
 ![Species](https://badgen.net/badge/Species/6512/blue)
 ![Downloads](https://www-user.tu-chemnitz.de/~johau/birdnet_total_downloads_badge.php)
+
 [![Docker](https://github.com/kahst/BirdNET-Analyzer/actions/workflows/docker-build.yml/badge.svg)](https://github.com/kahst/BirdNET-Analyzer/actions/workflows/docker-build.yml)
 [![Reddit](https://img.shields.io/badge/Reddit-FF4500?style=flat&logo=reddit&logoColor=white)](https://www.reddit.com/r/BirdNET_Analyzer/)
 ![GitHub stars)](https://img.shields.io/github/stars/kahst/BirdNET-Analyzer)
@@ -37,11 +38,9 @@ If you do, please cite as:
 }
 ```
 
-This work is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](http://creativecommons.org/licenses/by-nc-sa/4.0/).
-
 ## Documentation
 
-The documentation and further information will be listed [here](https://kahst.github.io/BirdNET-Analyzer/)
+You can access documentation for this project [here](https://kahst.github.io/BirdNET-Analyzer/).
 
 ## About
 
@@ -58,31 +57,23 @@ Want to use BirdNET to analyze a large dataset? Don't hesitate to contact us: cc
 - **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/).
 
-Please ensure you review and adhere to the specific license terms provided with each model. Note that educational and research purposes are considered non-commercial use cases.
-
-## Usage guide
-
-This document provides instructions for downloading and installing the GUI, and conducting some of the most common types of analyses. Within the document, a link is provided to download example sound files that can be used for practice.
-
-Download the PDF here: [BirdNET-Analyzer Usage Guide](https://zenodo.org/records/8357176)
-
-Watch our presentation on how to use BirdNET-Analyzer to train your own models: [BirdNET - BioacousTalks at YouTube](https://youtu.be/HuEZGIPeyq0)
+Please ensure you review and adhere to the specific license terms provided with each model.
 
-## Projects map
+*Please note that all educational and research purposes are considered non-commercial use and it is therefore freely permitted to use BirdNET models in any way.*
 
-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 [here](https://github.com/kahst/BirdNET-Analyzer/issues/221) and we can add it to the map.
+## Contribute
 
-You can access the map here: [Open projects map](https://kahst.github.io/BirdNET-Analyzer/projects.html)
+Feel free to clone this repository and contribute to the project. We are always looking for new ideas and improvements. If you have any questions, please don't hesitate to ask.
 
-## For Contributors
+Let us know if you have any ideas for new features or improvements or submit a pull request.
 
-### Building the docs locally
+**Help us to improve the documentation!**
 
 Install `sphinx` and all required themes + plugins with `pip install sphinx sphinx_rtd_theme sphinx-argparse`.
 
 Run `sphinx-build docs docs/_build`.
 
-Navige to `BirdNET-Analyzer/docs/_build` and open `index.html` with a browser of your choice.
+Navigate to `BirdNET-Analyzer/docs/_build` and open `index.html` with a browser of your choice.
 
 ## Funding
 

diff --git a/docs/best-practices.rst b/docs/best-practices.rst
@@ -0,0 +1,7 @@
+Best practices
+==============
+
+.. toctree::
+   :maxdepth: 2
+
+   best-practices/species-lists
diff --git a/docs/best-practices/species-lists.rst b/docs/best-practices/species-lists.rst
@@ -0,0 +1,10 @@
+Creating your own species list
+------------------------------
+
+When editing your own species_list.txt file, make sure to copy species names from the labels file of each model.
+
+You can find label files in the checkpoints folder, e.g., checkpoints/V2.4/BirdNET_GLOBAL_6K_V2.4_Labels.txt.
+
+Species names need to consist of scientific name_common name to be valid.
+
+You can generate a species list for a given location using :ref:`species.py <cli-species>`.
diff --git a/docs/faq.rst b/docs/faq.rst
@@ -1,13 +1,4 @@
 FAQ
 ===
 
-Creating your own species list
-------------------------------
-
-When editing your own species_list.txt file, make sure to copy species names from the labels file of each model.
-
-You can find label files in the checkpoints folder, e.g., checkpoints/V2.3/BirdNET_GLOBAL_3K_V2.3_Labels.txt.
-
-Species names need to consist of scientific name_common name to be valid.
-
-You can generate a species list for a given location using :ref:`species.py <cli-species>`.
+We will answer frequently asked questions here.
diff --git a/docs/index.rst b/docs/index.rst
@@ -10,13 +10,14 @@ Welcome to the BirdNET-Analyzer documentation! This guide provides detailed info
    installation
    usage
    models
+   best-practices
    faq
    showroom
 
 Introduction
 ------------
 
-BirdNET-Analyzer is an open-source tool for analyzing bird sounds using machine learning models. It processes audio recordings and identifies bird species based on their vocalizations.
+BirdNET-Analyzer is an open source tool for analyzing bird calls using machine learning models. It can process large amounts of audio recordings and identify (bird) species based on their calls.
 
 Citing BirdNET-Analyzer
 -----------------------
@@ -35,11 +36,6 @@ Feel free to use BirdNET for your acoustic analyses and research. If you do, ple
      publisher={Elsevier}
    }
 
-License
--------
-
-This work is licensed under a `Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License <https://creativecommons.org/licenses/by-nc-sa/4.0/>`_.
-
 About
 -----
 
@@ -51,4 +47,32 @@ Want to use BirdNET to analyze a large dataset? Don't hesitate to contact us: cc
 
 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.
+Have a question, remark, or feature request? Please start a new issue thread to let us know. Feel free to submit a pull request.
+
+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 `here <https://github.com/kahst/BirdNET-Analyzer/issues/221>`_ and we can add it to the map.
+
+You can access the map here: `Open projects map <https://kahst.github.io/BirdNET-Analyzer/projects.html>`_
+
+License
+-------
+
+   **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/>`_
+
+Please ensure you review and adhere to the specific license terms provided with each model.
+
+*Please note that all educational and research purposes are considered non-commercial use and it is therefore freely permitted to use BirdNET models in any way.*
+
+Funding
+-------
+
+This project is supported by Jake Holshuh (Cornell class of ´69) and The Arthur Vining Davis Foundations.
+Our work in the K. Lisa Yang Center for Conservation Bioacoustics is made possible by the generosity of K. Lisa Yang to advance innovative conservation technologies to inspire and inform the conservation of wildlife and habitats.
+
+The development of BirdNET is supported by the German Federal Ministry of Education and Research through the project “BirdNET+” (FKZ 01|S22072).
+The German Federal Ministry for the Environment, Nature Conservation and Nuclear Safety contributes through the “DeepBirdDetect” project (FKZ 67KI31040E).
+In addition, the Deutsche Bundesstiftung Umwelt supports BirdNET through the project “RangerSound” (project 39263/01).
diff --git a/docs/installation.rst b/docs/installation.rst
@@ -8,9 +8,11 @@ Raven Pro
 
 If you want to analyze audio files without any additional coding or package install, you can now use `Raven Pro software <https://ravensoundsoftware.com/software/raven-pro/>`_ to run BirdNET models.
 After download, BirdNET is available through the new "Learning detector" feature in Raven Pro.
-| For more information on how to use this feature, please visit the `Raven Pro Knowledge Base <https://ravensoundsoftware.com/article-categories/learning-detector/>`_.
 
-`Download the newest model version here <https://tuc.cloud/index.php/s/2TX59Qda2X92Ppr/download/BirdNET_GLOBAL_6K_V2.4_Model_Raven.zip>`_, extract the zip-file and move the extracted folder to the Raven models folder. On Windows, the models folder is `C:\\Users\\<Your user name>\\Raven Pro 1.6\\Models`. Start Raven Pro and select *BirdNET_GLOBAL_6K_V2.4_Model_Raven* as learning detector.
+For more information on how to use this feature, please visit the `Raven Pro Knowledge Base <https://ravensoundsoftware.com/article-categories/learning-detector/>`_.
+
+`Download the newest model version here <https://tuc.cloud/index.php/s/2TX59Qda2X92Ppr/download/BirdNET_GLOBAL_6K_V2.4_Model_Raven.zip>`_, extract the zip-file and move the extracted folder to the Raven models folder. 
+On Windows, the models folder is ``C:\Users\<Your user name>\Raven Pro 1.6\Models``. Start Raven Pro and select *BirdNET_GLOBAL_6K_V2.4_Model_Raven* as learning detector.
 
 Python Package
 --------------
@@ -51,13 +53,14 @@ When using the `birdnet`-package, you can run BirdNET with:
    print(f"predicted '{prediction}' with a confidence of {confidence:.6f}")
    # predicted 'Poecile atricapillus_Black-capped Chickadee' with a confidence of 0.814056
 
-| For more examples and documentation, make sure to visit `pypi.org/project/birdnet/ <https://pypi.org/project/birdnet/>`_.
-| For any feature request or questions regarding `birdnet`, please add an issue or PR at `github.com/birdnet-team/birdnet <https://github.com/birdnet-team/birdnet>`_.
+For more examples and documentation, make sure to visit `pypi.org/project/birdnet/ <https://pypi.org/project/birdnet/>`_.
+
+For any feature request or questions regarding `birdnet`, please add an issue or PR at `github.com/birdnet-team/birdnet <https://github.com/birdnet-team/birdnet>`_.
 
 Command line installation
 -------------------------
 
-Requires Python 3.10.
+Requires Python 3.10. or 3.11.
 
 Clone the repository
 
@@ -81,12 +84,8 @@ Verify the installation
 GUI installation
 ----------------
 
-You can download the latest BirdNET-Analyzer installer from our `Releases <https://github.com/kahst/BirdNET-Analyzer/releases/>`_ page. This installer provides an easy setup process for running BirdNET-Analyzer on your system. Make sure to check to select the correct installer for your system.
-
-.. note::
-
-   On Windows, the smartscreen filter might block the installer. In this case, click on "More info" and "Run anyway" to proceed with the installation.
+You can download the latest BirdNET-Analyzer installer for Windows and MacOS from our `Releases <https://github.com/kahst/BirdNET-Analyzer/releases/>`_ page. This installer provides an easy setup process for running BirdNET-Analyzer on your system. Make sure to check to select the correct installer for your system.
 
 .. note::
-    | NOTE: Installation was only tested on M1 and M2 chips.
+    | Installation was only tested on M1 and M2 chips.
     | Feedback on older Intel CPUs or newer M3 chips is welcome!
diff --git a/docs/models.rst b/docs/models.rst
@@ -42,12 +42,14 @@ Older models can also be used as custom classifiers in the GUI or using the `--c
 
 Just download your desired model version and unzip.
 
-| GUI: Select the \*_Model_FP32.tflite file under **Species selection > Custom classifier**
-| CLI: `python -m birdnet_analyzer ... --classifier <path_to_*_Model_FP32.tflite>`
+* GUI: Select the \*_Model_FP32.tflite file under **Species selection / Custom classifier**
+* CLI: ``python -m birdnet_analyzer ... --classifier 'path_to_Model_FP32.tflite'``
 
 Model Version History
 ---------------------
 
+.. note:: All models listed here 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/>`_.
+
 V2.4
 ^^^^