first commit

.bumpversion.cfg

@@ -0,0 +1,21 @@
+[bumpversion]
+current_version = 0.1.0
+
+[comment]
+comment = The contents of this file cannot be merged with that of setup.cfg until https://github.com/c4urself/bump2version/issues/185 is resolved
+
+[bumpversion:file:edg_acoustics/__init__.py]
+search = __version__ = "{current_version}"
+replace = __version__ = "{new_version}"
+
+[bumpversion:file:setup.cfg]
+search = version = {current_version}
+replace = version = {new_version}
+
+[bumpversion:file:CITATION.cff]
+search = version: "{current_version}"
+replace = version: "{new_version}"
+
+[bumpversion:file:docs/conf.py]
+search = version = "{current_version}"
+replace = version = "{new_version}"

.editorconfig

@@ -0,0 +1,26 @@
+# EditorConfig is awesome: http://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+charset = utf-8
+
+# 4 space indentation
+[*.{py,java,r,R}]
+indent_style = space
+indent_size = 4
+
+# 2 space indentation
+[*.{js,json,y{a,}ml,html,cwl}]
+indent_style = space
+indent_size = 2
+
+[*.{md,Rmd,rst}]
+trim_trailing_whitespace = false
+indent_style = space
+indent_size = 2

.githooks/pre-commit

@@ -0,0 +1,31 @@
+#!/bin/sh
+
+echo "Script $0 triggered ..."
+
+# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+echo "Starting prospector analysis using configuration from .prospector.yml..."
+
+# quietly run prospector
+prospector 1>/dev/null
+
+# use return code to abort commit if necessary
+if [ $? != "0" ]; then
+    echo "Commit aborted. Run 'prospector' to see the errors."
+    exit 1
+fi
+
+# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+echo "Starting isort analysis using configuration from setup.cfg..."
+
+# recursively run isort on edg_acoustics/ directory, don't try to automatically fix anything
+isort --recursive --check-only edg_acoustics
+
+if [ $? != "0" ]; then
+    echo "Commit aborted."
+    echo "  Run 'isort --recursive --check-only --diff edg_acoustics' to see what's wrong."
+    echo "  Run 'isort --recursive edg_acoustics' to let isort fix problems automatically."
+    exit 1
+fi
+
+echo "Pre-commit checks completed successfully."
+exit 0

.github/next_steps/01_sonarcloud_integration.md

@@ -0,0 +1,16 @@
+---
+title: 'Next step: Sonarcloud integration'
+---
+
+Continuous code quality can be handled by [Sonarcloud](https://sonarcloud.io/). This repository is configured to use Sonarcloud to perform quality analysis and code coverage report on each push.
+
+In order to configure Sonarcloud analysis [GitHub Action workflow](https://github.com/EDG-Acoustics/edg-acoustics/blob/main/.github/workflows/sonarcloud.yml) you must follow the steps below:
+
+1. go to [Sonarcloud](https://sonarcloud.io/projects/create) to create a new Sonarcloud project
+1. login with your GitHub account
+1. add Sonarcloud organization or reuse existing one
+1. set up a repository
+1. go to [new code definition administration page](https://sonarcloud.io/project/new_code?id=EDG-Acoustics_edg-acoustics) and select `Number of days` option
+1. To be able to run the analysis:
+   1. a token must be created at [Sonarcloud account](https://sonarcloud.io/account/security/)
+   1. the created token must be added as `SONAR_TOKEN` to [secrets on GitHub](https://github.com/EDG-Acoustics/edg-acoustics/settings/secrets/actions)

.github/next_steps/02_citation.md

@@ -0,0 +1,43 @@
+---
+title: 'Next step: Citation data'
+---
+
+It is likely that your `CITATION.cff` currently doesn't pass validation. The error messages you get from the [`cffconvert`](https://github.com/EDG-Acoustics/edg-acoustics/actions/workflows/cffconvert.yml) GitHub Action are unfortunately a bit cryptic, but doing the following helps:
+
+- [ ] Check if the `given-name` and `family-name` keys need updating. If your family name has a name particle like `von` or `van` or `de`, use the `name-particle` key; if your name has a suffix like `Sr` or `IV`, use `name-suffix`. For details, refer to the schema description: https://github.com/citation-file-format/citation-file-format
+- [ ] Update the value of the `orcid` key. If you do not have an orcid yet, you can get one here [https://orcid.org/](https://orcid.org/).
+- [ ] Add more authors if needed
+- [ ] Update `date-released` using the YYYY-MM-DD format.
+- [ ] Update the `doi` key with the conceptDOI for your repository (see [https://help.zenodo.org](https://help.zenodo.org/) for more information on what a conceptDOI is). If your project doesn't have a DOI yet, you can use the string `10.0000/FIXME` to pass validation.
+- [ ] Verify that the `keywords` array accurately describes your project.
+
+Once you do all the steps above, the `cffconvert` workflow will tell you what content it expected to see in `.zenodo.json`. Copy-paste from the GitHub Action log into a new file `.zenodo.json`. Afterwards, the `cffconvert` GitHub Action should be green.
+
+
+To help you keep the citation metadata up to date and synchronized, the [`cffconvert`](https://github.com/EDG-Acoustics/edg-acoustics/actions/workflows/cffconvert.yml) GitHub Action checks the following 6 aspects:
+
+1. Whether your repository includes a `CITATION.cff` file.
+
+    _By including this file, authors of the software can receive credit for the work they put in._
+
+1. Whether your `CITATION.cff` is valid YAML.
+
+    _Visit http://www.yamllint.com/ to see if the contents of your CITATION.cff are valid YAML._
+
+1. Whether your `CITATION.cff` adheres to the schema (as listed in the `CITATION.cff` file itself under key `cff-version`).
+
+    _The Citation File Format schema can be found [here](https://github.com/citation-file-format/citation-file-format), along with an explanation of all the keys. You're advised to use the latest available schema version._
+
+1. Whether your repository includes a `.zenodo.json` file.
+
+    _With this file, you can control what metadata should be associated with any future releases of your software on Zenodo: things like the author names, along with their affiliations and their ORCIDs, the license under which the software has been released, as well as the name of your software and a short description. If your repository doesn't have a .zenodo.json file, Zenodo will take a somewhat crude guess to assign these metadata._
+
+    _The `cffconvert` GitHub action will tell you what it expects to find in `.zenodo.json`, just copy and paste it to a new file named `.zenodo.json`. The suggested text ignores CITATION.cff's `version`, `commit`, and `date-released`. `cffconvert` considers these keys `suspect` in the sense that they are often out of date, and there is little purpose to telling Zenodo about these properties: Zenodo already knows._
+
+1. Whether `.zenodo.json` is valid JSON.
+
+    _Currently unimplemented, but you can check for yourself on [https://jsonlint.com/](https://jsonlint.com/)._ 
+
+1. Whether `CITATION.cff` and `.zenodo.json` contain equivalent data.
+
+    _This final check verifies that the two files are in sync. The check ignores CITATION.cff's `version`, `commit`, and `date-released`._

.github/next_steps/03_readthedocs.md

@@ -0,0 +1,20 @@
+---
+title: 'Next step: Read the Docs'
+---
+
+Your Python package should have publicly available documentation, including API documentation for your users.
+[Read the Docs](https://readthedocs.org) can host your user documentation for you.
+
+To host the documentation of this repository please perform the following instructions:
+
+1. go to [Read the Docs](https://readthedocs.org/dashboard/import/?)
+1. log in with your GitHub account
+1. find `EDG-Acoustics/edg-acoustics` in list and press `+` button.
+   * If repository is not listed,
+      1. go to [Read the Docs GitHub app](https://github.com/settings/connections/applications/fae83c942bc1d89609e2)
+      2. make sure EDG-Acoustics has been granted access.
+      3. reload repository list on Read the Docs import page
+1. wait for the first build to be completed at <https://readthedocs.org/projects/edg-acoustics/builds>
+1. check that the link of the documentation badge in the [README.md](https://github.com/EDG-Acoustics/edg-acoustics) works
+
+See [README.dev.md#](https://github.com/EDG-Acoustics/edg-acoustics/blob/main/README.dev.md#generating-the-api-docs) how to build documentation site locally.

.github/next_steps/04_zenodo_integration.md

@@ -0,0 +1,22 @@
+---
+title: 'Next step: Enable Zenodo integration'
+---
+
+By enabling Zenodo integration, your package will automatically get a DOI which can be used to cite your package. After enabling Zenodo integration for your GitHub repository, Zenodo will create a snapshot and archive each release you make on GitHub. Moreover, Zenodo will create a new DOI for each GitHub release of your code.
+
+To enable Zenodo integration:
+
+1. Go to http://zenodo.org and login with your GitHub account. When you are redirected to GitHub, *Authorize application* to give permission to Zenodo to access your account.
+1. Go to <https://zenodo.org/account/settings/github/> and enable Zenodo integration of your repository by clicking on `On` toggle button.
+2. Your package will get a DOI only after you make a release. Create a new release as described in [README.dev.md](https://github.com/EDG-Acoustics/edg-acoustics/blob/main/README.dev.md#33-github)
+3. At this point you should have a DOI. To find out the DOI generated by Zenodo:
+   1. Visit https://zenodo.org/deposit and click on your repository link
+   2. You will find the latest DOI in the right column in Versions box in **Cite all versions?** section
+   3. Copy the text of the link. For example `10.5281/zenodo.1310751`
+4. Update the badge in your repository
+   1. Edit README.md and replace the badge placeholder with the badge link you copied in previous step.
+   The badge placeholder is shown below.
+
+      `[![DOI](https://zenodo.org/badge/DOI/<replace-with-created-DOI>.svg)](https://doi.org/<replace-with-created-DOI>)`
+
+For FAQ about Zenodo please visit <https://help.zenodo.org/>.

.github/next_steps/05_linting.md

@@ -0,0 +1,17 @@
+---
+title: 'Next step: Linting'
+---
+
+Your repository has a [workflow](https://github.com/EDG-Acoustics/edg-acoustics/blob/main/.github/workflows/build.yml) which [lints](https://en.wikipedia.org/wiki/Lint_(software)) your code after every push and when creating a pull request.
+
+Linter workflow may fail if `description` or `keywords` field in [setup.cfg](https://github.com/EDG-Acoustics/edg-acoustics/blob/main/setup.cfg) is empty. Please update these fields. To validate your changes run:
+
+```shell
+prospector
+```
+
+Enabling [githook](https://git-scm.com/docs/githooks) will automatically lint your code in every commit. You can enable it by running the command below.
+
+```shell
+git config --local core.hooksPath .githooks
+```

.github/workflows/build.yml

@@ -0,0 +1,64 @@
+name: Python package
+
+on:
+  push:
+    branches:
+    - main
+  pull_request:
+    branches:
+    - main
+
+jobs:
+
+  build:
+    name: Build for (${{ matrix.python-version }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ['ubuntu-latest', 'macos-latest', 'windows-latest']
+        python-version: ['3.6', '3.7', '3.8', '3.9']
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v3
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Python info
+        shell: bash -l {0}
+        run: |
+          which python3
+          python3 --version
+      - name: Upgrade pip and install dependencies
+        run: |
+          python3 -m pip install --upgrade pip setuptools
+          python3 -m pip install .[dev,publishing]
+      - name: Run unit tests
+        run: pytest -v
+      - name: Verify that we can build the package
+        run: python3 setup.py sdist bdist_wheel
+
+  lint:
+    name: Linting build
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python 3.9
+        uses: actions/setup-python@v3
+        with:
+          python-version: 3.9
+      - name: Python info
+        shell: bash -l {0}
+        run: |
+          which python3
+          python3 --version
+      - name: Upgrade pip and install dependencies
+        run: |
+          python3 -m pip install --upgrade pip setuptools
+          python3 -m pip install .[dev,publishing]
+      - name: Check style against standards using prospector
+        run: prospector
+      - name: Check import order
+        run: isort --check-only edg_acoustics --diff

.github/workflows/cffconvert.yml

@@ -0,0 +1,21 @@
+name: cffconvert
+
+on:
+  push:
+    branches:
+    - main
+  pull_request:
+    branches:
+    - main
+
+jobs:
+
+  verify:
+    name: "cffconvert"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        name: Check out a copy of the repository
+
+      - uses: citation-file-format/cffconvert-github-action@main
+        name: Check whether the citation metadata from CITATION.cff is equivalent to that in .zenodo.json

.github/workflows/documentation.yml

@@ -0,0 +1,36 @@
+name: documentation
+
+on:
+  push:
+    branches:
+    - main
+  pull_request:
+    branches:
+    - main
+
+jobs:
+  build-documentation:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python 3.9
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.9
+      - name: Python info
+        shell: bash -l {0}
+        run: |
+          which python3
+          python3 --version
+      - name: Upgrade pip and install dependencies
+        run: |
+          python3 -m pip install --upgrade pip setuptools
+          python3 -m pip install .[dev,publishing]
+      - name: Install pandoc using apt
+        run: sudo apt install pandoc        
+      - name: Build documentation
+        run: make coverage doctest html
+        working-directory: docs

.github/workflows/markdown-link-check.yml

@@ -0,0 +1,20 @@
+name: markdown-link-check
+
+on:
+  push:
+    branches:
+    - main
+  pull_request:
+    branches:
+    - main
+
+jobs:
+
+  markdown-link-check:
+    name: Check markdown links
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: gaurav-nelson/github-action-markdown-link-check@v1
+      with:
+        config-file: '.mlc-config.json'