Skip to content

Commit e7608ff

Browse files
LilSpazJoekpLilSpazJoekp
authored
Merge pull request #147 from LilSpazJoekp/use-uv
Add CONTRIBUTING.rst and convert project to use uv
2 parents 06adbc1 + de2dcdb commit e7608ff

File tree

10 files changed

+2208
-66
lines changed

10 files changed

+2208
-66
lines changed

‎.github/workflows/ci.yaml‎

Lines changed: 26 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -17,14 +17,16 @@ jobs:
1717
with:
1818
cache: pip
1919
python-version: 3.x
20+
- name: Install uv
21+
uses: astral-sh/setup-uv@v4
22+
with:
23+
enable-cache: true
2024
- name: Install dependencies
21-
run: |
22-
python -m pip install --upgrade pip
23-
pip install .[lint]
25+
run: uv sync --group lint
2426
- name: Lint with pre-commit
25-
run: pre-commit run --all-files
27+
run: uv run pre-commit run --all-files
2628
- name: Run docstrfmt
27-
run: docstrfmt .
29+
run: uv run docstrfmt .
2830
strategy:
2931
matrix:
3032
os: [ macOS-latest, ubuntu-latest, windows-latest ]
@@ -35,16 +37,18 @@ jobs:
3537
runs-on: ${{ matrix.os }}
3638
steps:
3739
- uses: actions/checkout@v5
38-
- uses: actions/setup-python@v6
40+
- name: Set up Python
41+
uses: actions/setup-python@v6
3942
with:
40-
cache: pip
4143
python-version: 3.x
44+
- name: Install uv
45+
uses: astral-sh/setup-uv@v4
46+
with:
47+
enable-cache: true
4248
- name: Install dependencies
43-
run: |
44-
python -m pip install --upgrade pip
45-
pip install .[test]
49+
run: uv sync --group test
4650
- name: Test with pytest
47-
run: pytest
51+
run: uv run pytest
4852
strategy:
4953
matrix:
5054
os: [ macOS-latest, ubuntu-latest, windows-latest ]
@@ -53,23 +57,26 @@ jobs:
5357
runs-on: ubuntu-latest
5458
steps:
5559
- uses: actions/checkout@v5
56-
- uses: actions/setup-python@v6
60+
- name: Set up Python
61+
uses: actions/setup-python@v6
5762
with:
58-
cache: pip
63+
python-version: ${{ matrix.python-version }}
64+
- name: Install uv
65+
uses: astral-sh/setup-uv@v4
66+
with:
67+
enable-cache: true
5968
python-version: ${{ matrix.python-version }}
6069
- name: Install dependencies
61-
run: |
62-
python -m pip install --upgrade pip
63-
pip install .[ci,test]
70+
run: uv sync --group test --group ci
6471
- name: Test with pytest
65-
run: coverage run --source docstrfmt --module pytest
72+
run: uv run coverage run --source docstrfmt --module pytest
6673
- env:
6774
COVERALLS_PARALLEL: true
6875
COVERALLS_REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
6976
name: Submit to coveralls
70-
run: coveralls --service=github
77+
run: uv run coveralls --service=github
7178
- name: Check coverage
72-
run: coverage report -m --fail-under=100
79+
run: uv run coverage report -m --fail-under=100
7380
strategy:
7481
matrix:
7582
python-version: [ "3.10", "3.11", "3.12", "3.13", "3.14" ]

‎.pre-commit-config.yaml‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,9 @@
11
repos:
2+
- repo: https://github.com/astral-sh/uv-pre-commit
3+
# uv version.
4+
rev: 0.9.4
5+
hooks:
6+
- id: uv-lock
27
- repo: https://github.com/pre-commit/pre-commit-hooks
38
rev: v6.0.0
49
hooks:
@@ -29,8 +34,4 @@ repos:
2934
- id: ruff
3035
args: [ --exit-non-zero-on-fix, --fix ]
3136
files: ^(docstrfmt/.*.py)$
32-
33-
- repo: https://github.com/psf/black
34-
hooks:
35-
- id: black
36-
rev: 25.9.0
37+
- id: ruff-format

‎CONTRIBUTING.rst‎

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
Contributing to docstrfmt
2+
=========================
3+
4+
Thank you for your interest in contributing to docstrfmt! This document provides
5+
guidelines and instructions for contributing to the project.
6+
7+
Getting Started
8+
---------------
9+
10+
Prerequisites
11+
~~~~~~~~~~~~~
12+
13+
- Python 3.10 or higher
14+
- `uv <https://docs.astral.sh/uv/>`_ (recommended) or pip
15+
16+
Setting Up Your Development Environment
17+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18+
19+
1. Fork the repository on GitHub and clone your fork:
20+
21+
.. code-block:: sh
22+
23+
git clone https://github.com/YOUR-USERNAME/docstrfmt.git
24+
cd docstrfmt
25+
26+
2. Install uv (if not already installed):
27+
28+
.. code-block:: sh
29+
30+
# On macOS and Linux
31+
curl -LsSf https://astral.sh/uv/install.sh | sh
32+
33+
# On Windows
34+
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
35+
36+
3. Create a virtual environment and install dependencies:
37+
38+
.. code-block:: sh
39+
40+
uv sync --group dev
41+
42+
.. note::
43+
44+
The ``dev`` dependency group includes all the dependencies needed for
45+
development: linting tools, testing tools, and coverage reporting.
46+
47+
4. Install pre-commit hooks:
48+
49+
.. code-block:: sh
50+
51+
uv run pre-commit install
52+
53+
Development Workflow
54+
--------------------
55+
56+
Running Tests
57+
~~~~~~~~~~~~~
58+
59+
Run the test suite using pytest:
60+
61+
.. code-block:: sh
62+
63+
uv run pytest
64+
65+
Run tests with coverage:
66+
67+
.. code-block:: sh
68+
69+
uv run coverage run --source docstrfmt --module pytest
70+
uv run coverage report -m
71+
72+
Run tests across all Python versions using tox:
73+
74+
.. code-block:: sh
75+
76+
uv run tox
77+
78+
Run tests for a specific Python version:
79+
80+
.. code-block:: sh
81+
82+
# For Python 3.10
83+
uv run tox -e py310
84+
85+
Running Linters
86+
~~~~~~~~~~~~~~~
87+
88+
The project uses pre-commit hooks to ensure code quality. Run all checks:
89+
90+
.. code-block:: sh
91+
92+
uv run pre-commit run --all-files
93+
94+
You can also run pre-commit checks using tox:
95+
96+
.. code-block:: sh
97+
98+
uv run tox -e pre-commit
99+
100+
Run style checks:
101+
102+
.. code-block:: sh
103+
104+
uv run tox -e style
105+
106+
Run style checks and auto-fix issues:
107+
108+
.. code-block:: sh
109+
110+
uv run tox -e style-fix
111+
112+
Format the docs with docstrfmt:
113+
114+
.. code-block:: sh
115+
116+
uv run docstrfmt .
117+
118+
Running the Daemon
119+
~~~~~~~~~~~~~~~~~~
120+
121+
To test the daemon functionality, first install with the daemon extras:
122+
123+
.. code-block:: sh
124+
125+
uv sync --group dev --extra d
126+
127+
Then start the daemon:
128+
129+
.. code-block:: sh
130+
131+
uv run docstrfmtd
132+
133+
Code Style Guidelines
134+
---------------------
135+
136+
- Follow PEP 8 guidelines
137+
- Use type hints for function signatures
138+
- Write docstrings for all public modules, functions, classes, and methods
139+
- Keep line length to 88 characters (Black's default)
140+
- Use meaningful variable and function names
141+
142+
Making Changes
143+
--------------
144+
145+
1. Create a new branch for your changes:
146+
147+
.. code-block:: sh
148+
149+
git checkout -b feature/your-feature-name
150+
151+
2. Make your changes and ensure tests pass:
152+
153+
.. code-block:: sh
154+
155+
uv run pytest
156+
uv run pre-commit run --all-files
157+
158+
3. Commit your changes with a descriptive commit message:
159+
160+
.. code-block:: sh
161+
162+
git add .
163+
git commit -m "Add feature: description of your changes"
164+
165+
4. Push to your fork:
166+
167+
.. code-block:: sh
168+
169+
git push origin feature/your-feature-name
170+
171+
5. Open a Pull Request on GitHub
172+
173+
Pull Request Guidelines
174+
-----------------------
175+
176+
- Provide a clear description of the changes
177+
- Reference any related issues
178+
- Ensure all tests pass and coverage remains at 100%
179+
180+
Testing Guidelines
181+
------------------
182+
183+
- Write tests for all new features and bug fixes
184+
- Ensure all tests pass before submitting a PR
185+
- Maintain 100% test coverage
186+
- Use descriptive test names that explain what is being tested
187+
188+
Adding New Features
189+
-------------------
190+
191+
When adding new reStructuredText constructs or features:
192+
193+
1. Add test files in ``tests/test_files/``. These files should contain examples of
194+
properly formatted constructs.
195+
2. Implement the feature in the appropriate module
196+
3. Add tests in ``tests/test_main.py``
197+
4. Add an entry to CHANGES.rst

‎README.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -206,6 +206,12 @@ With pre-commit
206206
language_version: python3
207207
types_or: [python, rst, txt] # only needed if you want to include txt files.
208208
209+
Contributing
210+
------------
211+
212+
See `CONTRIBUTING.rst <CONTRIBUTING.rst>`_ for detailed information about setting up a
213+
development environment and contributing to the project.
214+
209215
.. _black: https://github.com/psf/black
210216

211217
.. _black's default line length: https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#line-length

‎docstrfmt/main.py‎

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@
2626
if sys.version_info >= (3, 11):
2727
import tomllib as toml # pragma: no cover
2828
else:
29-
import toml # pragma: no cover
29+
import tomli as toml # pragma: no cover
3030
from black import (
3131
DEFAULT_LINE_LENGTH,
3232
Mode,
@@ -135,11 +135,8 @@ def _parse_pyproject_config(
135135
value = pyproject_toml if pyproject_toml else None
136136
if value:
137137
try:
138-
if sys.version_info >= (3, 11):
139-
with open(value, "rb") as f: # pragma: no cover
140-
pyproject_toml = toml.load(f) # pragma: no cover
141-
else:
142-
pyproject_toml = toml.load(value) # pragma: no cover
138+
with open(value, "rb") as f:
139+
pyproject_toml = toml.load(f)
143140
config = pyproject_toml.get("tool", {}).get("docstrfmt", {})
144141
config = {
145142
k.replace("--", "").replace("-", "_"): v for k, v in config.items()
@@ -358,7 +355,7 @@ async def _run_formatter(
358355
for file in sorted(todo)
359356
}
360357
in_process = tasks.keys()
361-
try:
358+
try: # pragma: no cover
362359
loop.add_signal_handler(signal.SIGINT, cancel, in_process)
363360
loop.add_signal_handler(signal.SIGTERM, cancel, in_process)
364361
except NotImplementedError: # pragma: no cover

‎pre_push.py‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@
44
import argparse
55
import sys
66
from subprocess import CalledProcessError, check_call
7-
from tempfile import TemporaryDirectory
87

98

109
def do_process(args, shell=False):
@@ -65,7 +64,7 @@ def main():
6564
"-n",
6665
"--unstatic",
6766
action="store_true",
68-
help="Do not run static tests (black/flake8/pydocstyle/sphinx-build)",
67+
help="Do not run static tests (linting, formatting, etc.)",
6968
default=False,
7069
)
7170
parser.add_argument(

0 commit comments

Comments
 (0)