Skip to content

Commit 002d329

Browse files
cx1111cx1111
authored
Split README content into separate DEVELOPING document (#401)
* Remove outdated readthedocs content
1 parent a183c4d commit 002d329

File tree

3 files changed

+83
-95
lines changed

3 files changed

+83
-95
lines changed

‎DEVELOPING.md

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Developing WFDB-Python
2+
3+
## Guidelines
4+
5+
We welcome community contributions in the form of pull requests. When contributing code, please ensure:
6+
7+
- 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).
8+
- Unit tests are written for new features that are not covered by [existing tests](https://github.com/MIT-LCP/wfdb-python/tree/main/tests).
9+
- The code style is consistent with the project's formating standards.
10+
11+
Run the formatter with:
12+
13+
```sh
14+
black .
15+
```
16+
17+
## Package and Dependency Management
18+
19+
This project uses [poetry](https://python-poetry.org/docs/) for package management and distribution.
20+
21+
Development dependencies are specified as optional dependencies, and then added to the "dev" extra group in the [pyproject.toml](./pyproject.toml) file.
22+
23+
```sh
24+
# Do NOT use: poetry add <somepackage> --dev
25+
poetry add --optional <somepackage>
26+
```
27+
28+
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.
29+
30+
## Creating Distributions
31+
32+
Make sure the versions in [version.py](./wfdb/version.py) and [pyproject.toml](./pyproject.toml) are updated and kept in sync.
33+
34+
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.
35+
36+
Setup: configure access to repositories:
37+
38+
```sh
39+
# Create an API token, then add it
40+
poetry config pypi-token.pypi <my-token>
41+
42+
# For testpypi
43+
poetry config repositories.test-pypi https://test.pypi.org/legacy/
44+
poetry config pypi-token.test-pypi <my-testpypi-token>
45+
```
46+
47+
To build and upload a new distribution:
48+
49+
```sh
50+
poetry build
51+
52+
poetry publish -r test-pypi
53+
poetry publish
54+
```
55+
56+
## Creating Documentation
57+
58+
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: <http://wfdb.readthedocs.io>
59+
60+
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.
61+
62+
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.
63+
64+
To generate the HTML content locally, install the required dependencies and run from the `docs` directory:
65+
66+
```sh
67+
make html
68+
```
69+
70+
## Tests
71+
72+
Run tests using pytest:
73+
74+
```sh
75+
pytest
76+
# Distribute tests across multiple cores.
77+
# https://github.com/pytest-dev/pytest-xdist
78+
pytest -n auto
79+
```

‎README.md

Lines changed: 3 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -45,86 +45,12 @@ poetry install -E dev
4545
poetry install -E dev --no-root
4646
```
4747

48-
See the [note](#package-management) below about dev dependencies.
48+
**See the [note](https://github.com/MIT-LCP/wfdb-python/blob/main/DEVELOPING.md#package-and-dependency-management) about dev dependencies.**
4949

5050
## Developing
5151

52-
We welcome community contributions in the form of pull requests. When contributing code, please ensure:
53-
54-
- 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).
55-
- Unit tests are written for new features that are not covered by [existing tests](https://github.com/MIT-LCP/wfdb-python/tree/main/tests).
56-
- The code style is consistent with the project's formating standards.
57-
58-
Run the formatter with:
59-
60-
```sh
61-
black .
62-
```
63-
64-
### Package and Dependency Management
65-
66-
This project uses [poetry](https://python-poetry.org/docs/) for package management and distribution.
67-
68-
Development dependencies are specified as optional dependencies, and then added to the "dev" extra group in the [pyproject.toml](./pyproject.toml) file.
69-
70-
```sh
71-
# Do NOT use: poetry add <somepackage> --dev
72-
poetry add --optional <somepackage>
73-
```
74-
75-
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.
76-
77-
### Creating Distributions
78-
79-
Make sure the versions in [version.py](./wfdb/version.py) and [pyproject.toml](./pyproject.toml) are updated and kept in sync.
80-
81-
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.
82-
83-
Setup: configure access to repositories:
84-
85-
```sh
86-
# Create an API token, then add it
87-
poetry config pypi-token.pypi <my-token>
88-
89-
# For testpypi
90-
poetry config repositories.test-pypi https://test.pypi.org/legacy/
91-
poetry config pypi-token.test-pypi <my-testpypi-token>
92-
```
93-
94-
To build and upload a new distribution:
95-
96-
```sh
97-
poetry build
98-
99-
poetry publish -r test-pypi
100-
poetry publish
101-
```
102-
103-
### Creating Documentation
104-
105-
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: <http://wfdb.readthedocs.io>
106-
107-
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.
108-
109-
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.
110-
111-
To generate the HTML content locally, install the required dependencies and run from the `docs` directory:
112-
113-
```sh
114-
make html
115-
```
116-
117-
### Tests
118-
119-
Run tests using pytest:
120-
121-
```sh
122-
pytest
123-
# Distribute tests across multiple cores.
124-
# https://github.com/pytest-dev/pytest-xdist
125-
pytest -n auto
126-
```
52+
Please see the [DEVELOPING.md](https://github.com/MIT-LCP/wfdb-python/blob/main/DEVELOPING.md) document for contribution/development instructions.
12753

12854
## Citing
12955

130-
When using this resource, please cite the software [publication](https://physionet.org/content/wfdb-python/) oh PhysioNet.
56+
When using this resource, please cite the software [publication](https://physionet.org/content/wfdb-python/) on PhysioNet.

‎docs/index.rst

Lines changed: 1 addition & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -7,19 +7,7 @@ Introduction
77
The native Python waveform-database (WFDB) package. A library of tools
88
for reading, writing, and processing WFDB signals and annotations.
99

10-
Core components of this package are based on the original WFDB
11-
specifications. This package does not contain the exact same
12-
functionality as the original WFDB package. It aims to implement as many
13-
of its core features as possible, with user-friendly APIs. Additional
14-
useful physiological signal-processing tools are added over time.
15-
16-
17-
Development
18-
-----------
19-
20-
The development repository is hosted at: https://github.com/MIT-LCP/wfdb-python
21-
22-
The package is to be expanded with physiological signal-processing tools, and general improvements. Development is made for Python 3.6+ only.
10+
See the project home page and description at: https://github.com/MIT-LCP/wfdb-python
2311

2412

2513
API Reference
@@ -62,8 +50,3 @@ Indices and tables
6250
* :ref:`genindex`
6351
* :ref:`modindex`
6452
* :ref:`search`
65-
66-
67-
.. _PEP8: https://www.python.org/dev/peps/pep-0008/
68-
.. _docstrings: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
69-
.. _existing tests: https://github.com/MIT-LCP/wfdb-python/tree/main/tests

0 commit comments

Comments
 (0)