diff --git a/DEVELOPING.md b/DEVELOPING.md new file mode 100644 index 00000000..f78508b0 --- /dev/null +++ b/DEVELOPING.md @@ -0,0 +1,79 @@ +# Developing WFDB-Python + +## Guidelines + +We welcome community contributions in the form of pull requests. When contributing code, please ensure: + +- Documentation is provided. New functions and classes should have numpy/scipy style [docstrings](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt). +- Unit tests are written for new features that are not covered by [existing tests](https://github.com/MIT-LCP/wfdb-python/tree/main/tests). +- The code style is consistent with the project's formating standards. + +Run the formatter with: + +```sh +black . +``` + +## Package and Dependency Management + +This project uses [poetry](https://python-poetry.org/docs/) for package management and distribution. + +Development dependencies are specified as optional dependencies, and then added to the "dev" extra group in the [pyproject.toml](./pyproject.toml) file. + +```sh +# Do NOT use: poetry add --dev +poetry add --optional +``` + +The `[tool.poetry.dev-dependencies]` attribute is NOT used because of a [limitation](https://github.com/python-poetry/poetry/issues/3514) that prevents these dependencies from being pip installable. Therefore, dev dependencies are not installed when purely running `poetry install`, and the `--no-dev` flag has no meaning in this project. + +## Creating Distributions + +Make sure the versions in [version.py](./wfdb/version.py) and [pyproject.toml](./pyproject.toml) are updated and kept in sync. + +It may be useful to publish to testpypi and preview the changes before publishing to PyPi. However, the project dependencies likely will not be available when trying to install from there. + +Setup: configure access to repositories: + +```sh +# Create an API token, then add it +poetry config pypi-token.pypi + +# For testpypi +poetry config repositories.test-pypi https://test.pypi.org/legacy/ +poetry config pypi-token.test-pypi +``` + +To build and upload a new distribution: + +```sh +poetry build + +poetry publish -r test-pypi +poetry publish +``` + +## Creating Documentation + +The project's documentation is generated by [Sphinx](https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html) using the content in the [docs](./docs) directory. The generated content is then hosted on readthedocs (RTD) at: + +To manage the content on RTD, request yourself to be added to the [wfdb](https://readthedocs.org/projects/wfdb/) project. The project has already been configured to import content from the GitHub repository. Documentation for new releases should be automatically built and uploaded. See the [import guide](https://docs.readthedocs.io/en/stable/intro/import-guide.html) for more details. + +There is some redundancy in specifying the Sphinx requirements between pyproject.toml and [docs/requirements.txt](./docs/requirements.txt), the latter of which is used by RTD. Make sure that the content is consistent across the two files. + +To generate the HTML content locally, install the required dependencies and run from the `docs` directory: + +```sh +make html +``` + +## Tests + +Run tests using pytest: + +```sh +pytest +# Distribute tests across multiple cores. +# https://github.com/pytest-dev/pytest-xdist +pytest -n auto +``` diff --git a/README.md b/README.md index 2195b54e..564a32d8 100644 --- a/README.md +++ b/README.md @@ -45,86 +45,12 @@ poetry install -E dev poetry install -E dev --no-root ``` -See the [note](#package-management) below about dev dependencies. +**See the [note](https://github.com/MIT-LCP/wfdb-python/blob/main/DEVELOPING.md#package-and-dependency-management) about dev dependencies.** ## Developing -We welcome community contributions in the form of pull requests. When contributing code, please ensure: - -- Documentation is provided. New functions and classes should have numpy/scipy style [docstrings](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt). -- Unit tests are written for new features that are not covered by [existing tests](https://github.com/MIT-LCP/wfdb-python/tree/main/tests). -- The code style is consistent with the project's formating standards. - -Run the formatter with: - -```sh -black . -``` - -### Package and Dependency Management - -This project uses [poetry](https://python-poetry.org/docs/) for package management and distribution. - -Development dependencies are specified as optional dependencies, and then added to the "dev" extra group in the [pyproject.toml](./pyproject.toml) file. - -```sh -# Do NOT use: poetry add --dev -poetry add --optional -``` - -The `[tool.poetry.dev-dependencies]` attribute is NOT used because of a [limitation](https://github.com/python-poetry/poetry/issues/3514) that prevents these dependencies from being pip installable. Therefore, dev dependencies are not installed when purely running `poetry install`, and the `--no-dev` flag has no meaning in this project. - -### Creating Distributions - -Make sure the versions in [version.py](./wfdb/version.py) and [pyproject.toml](./pyproject.toml) are updated and kept in sync. - -It may be useful to publish to testpypi and preview the changes before publishing to PyPi. However, the project dependencies likely will not be available when trying to install from there. - -Setup: configure access to repositories: - -```sh -# Create an API token, then add it -poetry config pypi-token.pypi - -# For testpypi -poetry config repositories.test-pypi https://test.pypi.org/legacy/ -poetry config pypi-token.test-pypi -``` - -To build and upload a new distribution: - -```sh -poetry build - -poetry publish -r test-pypi -poetry publish -``` - -### Creating Documentation - -The project's documentation is generated by [Sphinx](https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html) using the content in the [docs](./docs) directory. The generated content is then hosted on readthedocs (RTD) at: - -To manage the content on RTD, request yourself to be added to the [wfdb](https://readthedocs.org/projects/wfdb/) project. The project has already been configured to import content from the GitHub repository. Documentation for new releases should be automatically built and uploaded. See the [import guide](https://docs.readthedocs.io/en/stable/intro/import-guide.html) for more details. - -There is some redundancy in specifying the Sphinx requirements between pyproject.toml and [docs/requirements.txt](./docs/requirements.txt), the latter of which is used by RTD. Make sure that the content is consistent across the two files. - -To generate the HTML content locally, install the required dependencies and run from the `docs` directory: - -```sh -make html -``` - -### Tests - -Run tests using pytest: - -```sh -pytest -# Distribute tests across multiple cores. -# https://github.com/pytest-dev/pytest-xdist -pytest -n auto -``` +Please see the [DEVELOPING.md](https://github.com/MIT-LCP/wfdb-python/blob/main/DEVELOPING.md) document for contribution/development instructions. ## Citing -When using this resource, please cite the software [publication](https://physionet.org/content/wfdb-python/) oh PhysioNet. +When using this resource, please cite the software [publication](https://physionet.org/content/wfdb-python/) on PhysioNet. diff --git a/docs/index.rst b/docs/index.rst index 2fdc76dd..88613163 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,19 +7,7 @@ Introduction The native Python waveform-database (WFDB) package. A library of tools for reading, writing, and processing WFDB signals and annotations. -Core components of this package are based on the original WFDB -specifications. This package does not contain the exact same -functionality as the original WFDB package. It aims to implement as many -of its core features as possible, with user-friendly APIs. Additional -useful physiological signal-processing tools are added over time. - - -Development ------------ - -The development repository is hosted at: https://github.com/MIT-LCP/wfdb-python - -The package is to be expanded with physiological signal-processing tools, and general improvements. Development is made for Python 3.6+ only. +See the project home page and description at: https://github.com/MIT-LCP/wfdb-python API Reference @@ -62,8 +50,3 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` - - -.. _PEP8: https://www.python.org/dev/peps/pep-0008/ -.. _docstrings: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt -.. _existing tests: https://github.com/MIT-LCP/wfdb-python/tree/main/tests