Repository: pyfar/sofar (language: python)

Issue:
Harmonize docs
- Update readme and contributing according to pyfar https://github.com/pyfar/pyfar/pull/590
- Remove examples and link to gallery instead


Discussion / hints:

Fix patch:
diff --git a/.circleci/config.yml b/.circleci/config.yml
index 0dde8f09..81dd413c 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -45,7 +45,7 @@ jobs:
           name: Run tests
           command: git submodule sync --recursive && git submodule update --recursive --init && pytest
 
-  flake:
+  ruff:
     parameters:
       version:
         description: "version tag"
@@ -63,7 +63,7 @@ jobs:
           pip-dependency-file: requirements_dev.txt
       - run:
           name: Flake8
-          command: git submodule sync --recursive && git submodule update --recursive --init && flake8 sofar tests
+          command: git submodule sync --recursive && git submodule update --recursive --init && ruff check
 
   test_documentation_build:
     parameters:
@@ -132,7 +132,7 @@ workflows:
                 - "3.10"
                 - "3.11"
                 - "3.12"
-      - flake:
+      - ruff:
           matrix:
             parameters:
               version:
@@ -168,7 +168,7 @@ workflows:
             tags:
               only: /^v[0-9]+(\.[0-9]+)*$/
 
-      - flake:
+      - ruff:
           matrix:
             parameters:
               version:
@@ -203,7 +203,7 @@ workflows:
                 - "3.12"
           requires:
             - build_and_test
-            - flake
+            - ruff
             - test_documentation_build
           filters:
             branches:
diff --git a/.coveragerc b/.coveragerc
deleted file mode 100644
index f1c2c59a..00000000
--- a/.coveragerc
+++ /dev/null
@@ -1,16 +0,0 @@
-[paths]
-source =
-   src/sofar
-   */site-packages/sofar
-
-[run]
-branch = true
-source =
-    sofar
-    tests
-parallel = true
-
-[report]
-show_missing = true
-precision = 2
-omit = *migrations*
diff --git a/.editorconfig b/.editorconfig
index 4000618e..09084781 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -1,13 +1,24 @@
-# see http://editorconfig.org
+# http://editorconfig.org
+
 root = true
 
 [*]
-end_of_line = lf
-trim_trailing_whitespace = true
-insert_final_newline = true
 indent_style = space
 indent_size = 4
+trim_trailing_whitespace = true
+insert_final_newline = true
 charset = utf-8
+end_of_line = lf
+
+[*.yml]
+indent_size = 2
 
-[*.{bat,cmd,ps1}]
+[*.bat]
+indent_style = tab
 end_of_line = crlf
+
+[LICENSE]
+insert_final_newline = false
+
+[Makefile]
+indent_style = tab
diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md
new file mode 100644
index 00000000..1e133d69
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE.md
@@ -0,0 +1,18 @@
+## General
+
+* sofar version:
+* Python version:
+* Operating System:
+* Did you install pyfar via pip:
+
+## Description
+
+Describe what you were trying to get done.
+Tell us what happened, what went wrong, and what you expected to happen.
+
+## What I Did
+
+```
+Paste the command(s) you ran and the output.
+If there was a crash, please include the traceback here.
+```
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 00000000..dd5be6ff
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,9 @@
+### Which issue(s) are closed by this pull request?
+
+Closes #
+
+### Changes proposed in this pull request:
+
+-
+-
+-
diff --git a/.github/workflows/create_issue_if_cookiecutter.yml b/.github/workflows/create_issue_if_cookiecutter.yml
new file mode 100644
index 00000000..ba4337b9
--- /dev/null
+++ b/.github/workflows/create_issue_if_cookiecutter.yml
@@ -0,0 +1,25 @@
+on:
+  pull_request:
+    types: [ labeled ]
+name: Create issue if pr gets a cookiecutter label
+jobs:
+  stuff:
+    permissions:
+      contents: read
+      issues: write
+    name: create issue
+    environment: test
+    if: github.event.label.name == 'cookiecutter'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          repository: 'pyfar/cookiecutter-pypackage'
+      - uses: dacbd/create-issue-action@v2
+        with:
+          title: ${{ github.event.pull_request.title  }}
+          token: ${{ secrets.cookiecutter_PAT }}
+          owner: pyfar
+          repo: cookiecutter-pypackage
+          body: |
+            apply changes from https://github.com/${{ github.repository }}/pull/${{ github.event.number }}
diff --git a/.gitignore b/.gitignore
index 372e9192..2edc775b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,73 +1,119 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
 *.py[cod]
+*$py.class
 
 # C extensions
 *.so
 
-# Packages
-*.egg
-*.egg-info
-dist
-build
-eggs
-.eggs
-parts
-bin
-var
-sdist
-wheelhouse
-develop-eggs
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
 .installed.cfg
-lib
-lib64
-venv*/
-env/
-pyvenv*/
-.pytest_cache/
-**/__pycache__/
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
 
 # Installer logs
 pip-log.txt
+pip-delete-this-directory.txt
 
 # Unit test / coverage reports
+htmlcov/
 .coverage
 .coverage.*
+.cache
 nosetests.xml
 coverage.xml
-htmlcov
+*.cover
+.hypothesis/
+.pytest_cache/
 
 # Translations
 *.mo
+*.pot
 
-# Mr Developer
-.mr.developer.cfg
-.project
-.pydevproject
-.idea
-*.iml
-*.komodoproject
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
 
-# Complexity
-output/*.html
-output/*/index.html
+# Flask stuff:
+instance/
+.webassets-cache
 
-# Sphinx
-docs/_build
+# Scrapy stuff:
+.scrapy
 
-.DS_Store
-.vscode
-*~
-.*.sw[po]
-.build
-.ve
+# Sphinx documentation
+docs/_build/
+docs/_autosummary
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+*/.ipynb_checkpoints/*
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
 .env
-.cache
-.pytest
-.bootstrap
-.appveyor.token
-*.bak
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# vs code
+.vscode/
+.idea/
+
+# macOS
+.DS_Store
 
-# Private tests
-tests/private
+# workaround for failing test discovery in vscode
+tests/*/__init__.py
+tests/private/
 
 # ignore downloads from pyfar gallery
 docs/header.rst
@@ -75,3 +121,4 @@ docs/_static/favicon.ico
 docs/_static/header.rst
 docs/_static/css/custom.css
 docs/resources/logos/pyfar_logos_fixed_size_sofar.png
+docs/resources/conventions.rst
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index b578b933..90e6ed58 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -10,8 +10,6 @@ contributing specifically to sofar. Please also consider the
 `general contributing guidelines`_ for example regarding the style
 of code and documentation and some helpful hints.
 
-You can contribute in many ways:
-
 Types of Contributions
 ----------------------
 
@@ -36,19 +34,18 @@ articles, and such.
 Get Started!
 ------------
 
-Ready to contribute? Here's how to set up `sofar` for local development.
+Ready to contribute? Here's how to set up `sofar` for local development using the command-line interface. Note that several alternative user interfaces exist, e.g., the Git GUI, `GitHub Desktop <https://desktop.github.com/>`_, extensions in `Visual Studio Code <https://code.visualstudio.com/>`_ ...
 
-1. Fork the `sofar` repo on GitHub.
+1. `Fork <https://docs.github.com/en/get-started/quickstart/fork-a-repo/>`_ the `sofar` repo on GitHub.
 2. Clone your fork locally and cd into the sofar directory::
 
-    $ git clone --recursive https://github.com/pyfar/sofar.git
-    $ cd sofar/
-
-3. Note that some graphical Git interfaces can not do the recursive clone. If the folder sofar/sofa_conventions is empty try
+    $ git clone --recursive https://github.com/YOUR_USERNAME/sofar.git
+    $ cd sofar
+    Note that some graphical Git interfaces can not do the recursive clone. If the folder sofar/sofa_conventions is empty try::
 
     $ git submodule update --init
 
-4. Install your local copy into a virtualenv. Assuming you have Anaconda or Miniconda installed, this is how you set up your fork for local development::
+3. Install your local copy into a virtualenv. Assuming you have Anaconda or Miniconda installed, this is how you set up your fork for local development::
 
     $ conda create --name sofar python
     $ conda activate sofar
@@ -56,27 +53,28 @@ Ready to contribute? Here's how to set up `sofar` for local development.
     $ pip install -e .
     $ pip install -r requirements_dev.txt
 
-5. Create a branch for local development. Indicate the intention of your branch in its respective name (i.e. `feature/branch-name` or `bugfix/branch-name`)::
+4. Create a branch for local development. Indicate the intention of your branch in its respective name (i.e. `feature/branch-name` or `bugfix/branch-name`)::
 
     $ git checkout -b name-of-your-bugfix-or-feature
 
    Now you can make your changes locally.
 
-6. When you're done making changes, check that your changes pass flake8 and the
+5. When you're done making changes, check that your changes pass ruff and the
    tests::
 
-    $ flake8 sofar tests
+    $ ruff check
     $ pytest
 
-   flake8 test must pass without any warnings for `./sofar` and `./tests` using the default or a stricter configuration. Flake8 ignores `E123/E133, E226` and `E241/E242` by default. If necessary adjust the your flake8 and linting configuration in your IDE accordingly.
+   ruff must pass without any warnings for `./sofar` and `./tests` using the default or a stricter configuration. Ruff ignores a couple of PEP Errors (see `./pyproject.toml`). If necessary, adjust your linting configuration in your IDE accordingly.
 
-7. Commit your changes and push your branch to GitHub::
+6. Commit your changes and push your branch to GitHub::
 
     $ git add .
     $ git commit -m "Your detailed description of your changes."
     $ git push origin name-of-your-bugfix-or-feature
 
-8. Submit a pull request through the GitHub website.
+7. Submit a pull request on the develop branch through the GitHub website.
+
 
 Submodules
 ~~~~~~~~~~
diff --git a/HISTORY.rst b/HISTORY.rst
index 9ebd89f2..32f23c6d 100644
--- a/HISTORY.rst
+++ b/HISTORY.rst
@@ -1,3 +1,4 @@
+=======
 History
 =======
 
@@ -77,4 +78,4 @@ History
 
 0.1.0 (2021-10-29)
 ------------------
-* First release on PyPI
\ No newline at end of file
+* First release on PyPI
diff --git a/LICENSE b/LICENSE
index d53f9a00..e345fa45 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,4 +1,6 @@
-Copyright (c) [2021] [The pyfar developers]
+MIT License
+
+Copyright (c) 2021, The pyfar developers
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -17,3 +19,4 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
diff --git a/MANIFEST.in b/MANIFEST.in
index c0cc2fae..2f355326 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,4 +1,3 @@
-include AUTHORS.rst
 include CONTRIBUTING.rst
 include HISTORY.rst
 include LICENSE
@@ -10,3 +9,9 @@ recursive-include sofar/sofa_conventions/conventions *.json
 recursive-include sofar/sofa_conventions/conventions/deprecated *.csv
 recursive-include sofar/sofa_conventions/conventions/deprecated *.json
 recursive-include sofar/sofa_conventions/rules *.json
+
+recursive-include tests *
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+
+recursive-include docs *.rst conf.py Makefile make.bat *.jpg *.png *.gif
diff --git a/docs/Makefile b/docs/Makefile
index 89b0969d..70c74037 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -4,7 +4,7 @@
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = python -msphinx
-SPHINXPROJ    = pyfar
+SPHINXPROJ    = sofar
 SOURCEDIR     = .
 BUILDDIR      = _build
 
diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
new file mode 100644
index 00000000..86b1cea7
--- /dev/null
+++ b/docs/_static/css/custom.css
@@ -0,0 +1,11 @@
+
+html[data-theme="light"] {
+    --pst-color-primary: #18609d; /* pyfar blue as primary color */
+}
+
+html[data-theme="dark"] {
+    --pst-color-primary: #18609d; /* pyfar blue as primary color */
+}
+html {
+    --pst-icon-external-link: "";
+}
\ No newline at end of file
diff --git a/docs/authors.rst b/docs/authors.rst
deleted file mode 100644
index e122f914..00000000
--- a/docs/authors.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-.. include:: ../AUTHORS.rst
diff --git a/docs/conf.py b/docs/conf.py
index b5b3845d..86da3654 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -40,8 +40,6 @@
 # package matplotlib.sphinxext.plot_directive
 plot_include_source = True
 
-imgmath_latex_preamble = r'\usepackage{array}'
-
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -66,9 +64,6 @@
 # The full version, including alpha/beta/rc tags.
 release = sofar.__version__
 
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
 language = 'en'
@@ -94,9 +89,6 @@
 # intersphinx mapping
 intersphinx_mapping = {
     'numpy': ('https://numpy.org/doc/stable/', None),
-    'scipy': ('https://docs.scipy.org/doc/scipy/', None),
-    'matplotlib': ('https://matplotlib.org/stable/', None),
-    'pyfar': ('https://pyfar.readthedocs.io/en/stable/', None),
     'gallery': ('https://pyfar-gallery.readthedocs.io/en/latest/', None),
     }
 
@@ -136,9 +128,9 @@
    "default_mode": "light"
 }
 
-# redirect index to sofar.html
+# redirect index to pyfar.html
 redirects = {
-     "index": "sofar.html"
+     "index": f"{project}.html"
 }
 
 # -- download navbar and style files from gallery -----------------------------
diff --git a/docs/make.bat b/docs/make.bat
index 1f4a59ad..006676a6 100644
--- a/docs/make.bat
+++ b/docs/make.bat
@@ -1,36 +1,36 @@
-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=python -msphinx
-)
-set SOURCEDIR=.
-set BUILDDIR=_build
-set SPHINXPROJ=pyfar
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
-	echo.
-	echo.The Sphinx module was not found. Make sure you have Sphinx installed,
-	echo.then set the SPHINXBUILD environment variable to point to the full
-	echo.path of the 'sphinx-build' executable. Alternatively you may add the
-	echo.Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
-	exit /b 1
-)
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
-
-:end
-popd
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=python -msphinx
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+set SPHINXPROJ=sofar
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The Sphinx module was not found. Make sure you have Sphinx installed,
+	echo.then set the SPHINXBUILD environment variable to point to the full
+	echo.path of the 'sphinx-build' executable. Alternatively you may add the
+	echo.Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd
diff --git a/docs/requirements.txt b/docs/requirements.txt
deleted file mode 100644
index 8a8a4047..00000000
--- a/docs/requirements.txt
+++ /dev/null
@@ -1,3 +0,0 @@
-sphinx>=1.3
-sphinx-rtd-theme
--e .
diff --git a/docs/resources/conventions.py b/docs/resources/conventions.py
index c7aae37f..1fe5f78c 100644
--- a/docs/resources/conventions.py
+++ b/docs/resources/conventions.py
@@ -49,7 +49,7 @@
     '  * **M:** Number of measurements\n'
     '  * **N:** Number of samples or frequency bins of the data\n'
     '  * **C:** Number of coordinates (always 3)\n'
-    '  * **I:** Unity dimentions (always 1)\n'
+    '  * **I:** Unity dimensions (always 1)\n'
     '  * **S:** Lengths of the longest string contained in the data '
     '(detected automatically)\n\n'
     '* **Flags:**\n\n'
diff --git a/docs/sofar.rst b/docs/sofar.rst
index 892a66d7..a0f1d3a6 100644
--- a/docs/sofar.rst
+++ b/docs/sofar.rst
@@ -1,50 +1,37 @@
-Getting Started
-===============
+sofar
+=====
 
 .. toctree::
-   :maxdepth: 2
+   :caption: Getting Started
+   :maxdepth: 1
 
    readme
 
 
-Documentation
-=============
-
 .. toctree::
+   :caption: Documentation
    :maxdepth: 2
 
    sofar.Sofa
    sofar.functions
-
-
-SOFA conventions
-================
+   
 
 .. toctree::
+   :caption: SOFA conventions
    :maxdepth: 1
 
    resources/conventions
 
-Contributing
-===============
 
 .. toctree::
-   :maxdepth: 2
+   :caption: Contributing
+   :maxdepth: 1
 
    contributing
 
-Other
-=====
+
 .. toctree::
+   :caption: Other
    :maxdepth: 1
 
-   authors
    history
-
-..
-   (removed because it is contained in the new spinx style)
-   Indices and tables
-   ==================
-   * :ref:`genindex`
-   * :ref:`modindex`
-   * :ref:`search`
diff --git a/environment.yml b/environment.yml
new file mode 100644
index 00000000..e0d5e102
--- /dev/null
+++ b/environment.yml
@@ -0,0 +1,13 @@
+name: sofar
+channels:
+  - defaults
+  - conda-forge
+dependencies:
+  - python=3.12
+  - pip
+  - numpy>=1.14.0
+  - pip:
+    - netCDF4
+    - beautifulsoup4
+    - requests
+    - packaging
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 00000000..59c13b3e
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,13 @@
+[tool.ruff]
+exclude = [
+    ".git",
+    "docs",
+    "setup.py",
+]
+line-length = 79
+lint.ignore = []
+lint.select = [
+    "E",
+    "F",
+    "W",
+]
diff --git a/requirements_dev.txt b/requirements_dev.txt
index d47461a8..9d8931ad 100644
--- a/requirements_dev.txt
+++ b/requirements_dev.txt
@@ -2,7 +2,7 @@ pip
 bump2version
 wheel
 watchdog
-flake8
+ruff==0.4.1
 coverage
 Sphinx
 twine
@@ -12,7 +12,6 @@ pytest-cov
 numpy>=1.14.0
 scipy>=1.5.0
 deepdiff
-tox-wheel
 autodocsumm
 netCDF4
 beautifulsoup4
diff --git a/setup.cfg b/setup.cfg
index 05b07279..6597c95b 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -13,9 +13,5 @@ replace = __version__ = '{new_version}'
 
 [bdist_wheel]
 universal = 1
-
-[flake8]
-exclude = .git, docs
-
 [aliases]
 test = pytest
diff --git a/setup.py b/setup.py
index 6997705d..11a61306 100644
--- a/setup.py
+++ b/setup.py
@@ -19,18 +19,20 @@
     'packaging'
 ]
 
-setup_requirements = ['pytest-runner', ]
+setup_requirements = [
+    'pytest-runner',
+]
 
 test_requirements = [
-    'pip'
     'pytest',
     'bump2version',
     'wheel',
     'watchdog',
-    'flake8',
+    'ruff',
     'coverage',
     'Sphinx',
-    'twine'
+    'twine',
+    'pydata-sphinx-theme',
 ]
 
 setup(
@@ -46,7 +48,7 @@
         'Programming Language :: Python :: 3.9',
         'Programming Language :: Python :: 3.10',
         'Programming Language :: Python :: 3.11',
-        'Programming Language :: Python :: 3.12'
+        'Programming Language :: Python :: 3.12',
     ],
     description="Maybe the most complete python package for SOFA files so far",
     install_requires=requirements,
@@ -68,5 +70,5 @@
     },
     version='1.1.3',
     zip_safe=False,
-    python_requires='>=3.8'
+    python_requires='>=3.8',
 )


Test patch:
diff --git a/pytest.ini b/pytest.ini
index 94aaf7d4..445c908c 100644
--- a/pytest.ini
+++ b/pytest.ini
@@ -1,5 +1,4 @@
 # pytest.ini
 [pytest]
 norecursedirs = private
-filterwarnings = ignore::UserWarning
 testpaths = tests