Skip to content

Commit aba20aa

Browse files
lagrulagru
authored
Prepare release of version 0.3.0 (#51)
* Update classifiers and pyproject.toml metadata * Test on Python 3.13 in CI too * Draft release workflow in cd.yml The draft combines ideas from [1], [2] and [3] [1] https://github.com/pypa/gh-action-pypi-publish [2] https://github.com/scientific-python/repo-review/blob/6d8de35b2fd98c187f86fdcde526eca2bd45f23a/.github/workflows/cd.yml [3] https://github.com/scientific-python/spin/blob/fee6abe42cea118c2e4577cce5e0ca034c55748e/.github/workflows/release.yml * WIP Draft release notes with changelist * Add basic release notes from old 0.2.0 release * Add a section on "Dealing with typing problems" * Improve release notes for 0.3 * Use absolute link in README which is included on PyPI where a relative one wouldn't work.
1 parent 4169977 commit aba20aa

File tree

7 files changed

+206
-8
lines changed

7 files changed

+206
-8
lines changed

‎.github/workflows/cd.yml

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
name: CD
2+
3+
on:
4+
workflow_dispatch:
5+
release:
6+
types:
7+
- published
8+
9+
10+
env:
11+
# Many color libraries just need this to be set to any value, but at least
12+
# one distinguishes color depth, where "3" -> "256-bit color".
13+
FORCE_COLOR: 3
14+
15+
16+
jobs:
17+
pypi-publish:
18+
name: Build & publish to PyPI
19+
runs-on: ubuntu-latest
20+
environment:
21+
name: release
22+
url: https://pypi.org/p/docstub
23+
permissions:
24+
id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
25+
steps:
26+
- uses: actions/checkout@v4
27+
with:
28+
fetch-depth: 0
29+
30+
- uses: actions/setup-python@v5
31+
with:
32+
python-version: "3.13"
33+
34+
- name: Build wheel & sdist
35+
run: |
36+
git clean -fxd
37+
pip install -U build twine wheel
38+
python -m build --sdist --wheel
39+
40+
- name: Publish to PyPI
41+
uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4

‎.github/workflows/ci.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ jobs:
4747
- { short: linux, name: ubuntu-latest }
4848
- { short: win, name: windows-latest }
4949
- { short: macos, name: macos-14 }
50-
python-version: ["3.12"]
50+
python-version: ["3.12", "3.13"]
5151

5252
steps:
5353
- uses: actions/checkout@v4

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ It does so by supporting widely used readable conventions such as `array of dtyp
1616

1717
## Installation & getting started
1818

19-
Please refer to the [user guide](docs/user_guide.md) to get started with docstub.
19+
Please refer to the [user guide](https://github.com/scientific-python/docstub/blob/main/docs/user_guide.md) to get started with docstub.
2020

2121

2222
## Contributing

‎docs/release_notes/v0.2.0.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
## docstub 0.2.0
2+
3+
A first prototype of the tool with the following features:
4+
5+
- Given a source directory `examples/example_pkg`, create a stub files for
6+
every contained Python file in `examples/example-stubs/`
7+
- No need to import the source package!
8+
- PYI files that already exist in the source package take precedence and are
9+
copied directly
10+
- Type description in NumPy style docstrings are parsed and transformed into
11+
Python ready type annotations
12+
- supports `tuple of float` like syntax
13+
- supports array syntax like: `(N,) uint8 array-like` or
14+
`array of dtype float and shape (10, ..., 3)` (shape is discarded for now)
15+
- supports literals like `{"reflect", "mirror", "constant"}`
16+
- supports `<some type>, optional, extra information`
17+
- see included `examples/` for more...
18+
- `Any` is used wherever types are missing, except for the first parameter of
19+
methods and classmethods
20+
- Specify how used types can be imported via a map in
21+
`docstub.toml::[tool.docstub.docnames]`. Imports using `from` and `as` are
22+
supported. This map can also serve to provide synonyms.
23+
- Created stub files are automatically formatted with isort and black, if these
24+
optional dependencies are available.

‎docs/release_notes/v0.3.0.md

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# docstub 0.3.0
2+
3+
This release marks the first "Alpha" release of docstub. 🎉
4+
5+
## Highlights
6+
7+
- **A revamped command line interface**
8+
Stubs are created with the new subcommand `docstub run` which leaves room to add other subcommands in the future ([#49](https://github.com/scientific-python/docstub/pull/49)).
9+
The new subcommand also includes two new options `--group-errors` ([#30](https://github.com/scientific-python/docstub/pull/30)) and `--allow-errors` to help with adopting docstub gradually ([#32](https://github.com/scientific-python/docstub/pull/32)).
10+
11+
- **Improved error reporting and statistics**
12+
When docstub encounters errors in the package it is running on it will now point at the file and line where they are originating from ([#10](https://github.com/scientific-python/docstub/pull/10)).
13+
Similarly, docstub will report the total number of errors, types that it didn't know where to import from and the total runtime.
14+
15+
- **Improved typing support**
16+
Module and class attributes can now be typed in docstrings too ([#18](https://github.com/scientific-python/docstub/pull/18)).
17+
This includes support for the special case of dataclasses ([#26](https://github.com/scientific-python/docstub/pull/26)).
18+
You can now document generator functions with the "Yields" and "Receives" docstring sections ([#29](https://github.com/scientific-python/docstub/pull/29)).
19+
For edge cases, that docstub doesn't yet (correctly) support, you can now wrap lines in `# docstub: off` and `# docstub: on`.
20+
This selectively prevents docstub from changing lines during stub creation ([#25](https://github.com/scientific-python/docstub/pull/25)).
21+
22+
- **Improved configuration**
23+
Simplified the configuration file.
24+
Declaring external types should be a lot more straightforward.
25+
A reference for the configuration file is scheduled for the next release ([#45](https://github.com/scientific-python/docstub/pull/45)).
26+
27+
- We added a **user guide** to get started with using docstub as well as a **reference** for the extended typing syntax that can be used in docstrings ([#24](https://github.com/scientific-python/docstub/pull/24)).
28+
29+
Find a more detailed list of pull requests contributing to this release below.
30+
31+
## Enhancement
32+
33+
- Stub files are now created inplace if no explicit output directory is specified.
34+
Pre-existing stub files that are not managed by docstub are preserved as before ([#28](https://github.com/scientific-python/docstub/pull/28)).
35+
- You can now indicate a plural with `(s)` in expressions like `list of int(s)` ([#37](https://github.com/scientific-python/docstub/pull/37)).
36+
The grammar supporting the typing syntax in docstring should be better behaved for edge cases now.
37+
- Collect docnames of analyzed source in advance ([#2](https://github.com/scientific-python/docstub/pull/2)).
38+
- Point to precise line in parsed source for parsing problems ([#10](https://github.com/scientific-python/docstub/pull/10)).
39+
- Support attributes and type aliases ([#18](https://github.com/scientific-python/docstub/pull/18)).
40+
- Add direct support for dataclasses ([#26](https://github.com/scientific-python/docstub/pull/26)).
41+
- Support Yields section and Generator functions ([#29](https://github.com/scientific-python/docstub/pull/29)).
42+
- Add `--group-errors` option ([#30](https://github.com/scientific-python/docstub/pull/30)).
43+
- Add `--allow-errors` command line option ([#32](https://github.com/scientific-python/docstub/pull/32)).
44+
- Support combined NumPyDoc params ([#41](https://github.com/scientific-python/docstub/pull/41)).
45+
46+
## Bug Fixes
47+
48+
- Only use `| None` for optional parameters if appropriate ([#14](https://github.com/scientific-python/docstub/pull/14)).
49+
- Check test suite with mypy ([#27](https://github.com/scientific-python/docstub/pull/27)).
50+
- fix check for length 1 literal ([#40](https://github.com/scientific-python/docstub/pull/40)).
51+
- Allow signed numbers in literals ([#46](https://github.com/scientific-python/docstub/pull/46)).
52+
53+
## Performance
54+
55+
- Types collected while creating stubs for a package are now cached so that the next run is a lot faster ([#15](https://github.com/scientific-python/docstub/pull/15)).
56+
57+
## Documentation
58+
59+
- Attribute copyright to Scientific Python Developers ([#4](https://github.com/scientific-python/docstub/pull/4)).
60+
- Reword descriptions in manual ([#23](https://github.com/scientific-python/docstub/pull/23)).
61+
- Refactor and document doctype grammar ([#33](https://github.com/scientific-python/docstub/pull/33)).
62+
- Add minimal documentation ([#24](https://github.com/scientific-python/docstub/pull/24)).
63+
64+
## Devops
65+
66+
- Add basic CI configuration ([#8](https://github.com/scientific-python/docstub/pull/8)).
67+
- Enable doctests by default ([#12](https://github.com/scientific-python/docstub/pull/12)).
68+
- Use mypy.stubtest in CI ([#25](https://github.com/scientific-python/docstub/pull/25)).
69+
- Check test suite with mypy ([#27](https://github.com/scientific-python/docstub/pull/27)).
70+
- Check `tests/` with basedpyright in CI in "standard" mode ([#50](https://github.com/scientific-python/docstub/pull/50)).
71+
- Prepare release of version 0.3.0 ([#51](https://github.com/scientific-python/docstub/pull/51)).
72+
73+
## Maintenance
74+
75+
- Fix python_requires ([#5](https://github.com/scientific-python/docstub/pull/5)).
76+
- Refactor and document doctype grammar ([#33](https://github.com/scientific-python/docstub/pull/33)).
77+
- Update import for Generator and Callable types ([#34](https://github.com/scientific-python/docstub/pull/34)).
78+
- Refactor configuration fields ([#45](https://github.com/scientific-python/docstub/pull/45)).
79+
- Add minimal documentation ([#24](https://github.com/scientific-python/docstub/pull/24)).
80+
- Move main CLI functionality into `docstub run` subcommand ([#49](https://github.com/scientific-python/docstub/pull/49)).
81+
82+
## Contributors
83+
84+
3 authors added to this release (alphabetically):
85+
86+
- Lars Grüter ([@lagru](https://github.com/lagru))
87+
- Marianne Corvellec ([@mkcor](https://github.com/mkcor))
88+
- Oriol Abril-Pla ([@OriolAbril](https://github.com/OriolAbril))
89+
90+
4 reviewers added to this release (alphabetically):
91+
92+
- Brigitta Sipőcz ([@bsipocz](https://github.com/bsipocz))
93+
- Lars Grüter ([@lagru](https://github.com/lagru))
94+
- Marianne Corvellec ([@mkcor](https://github.com/mkcor))
95+
- Oriol Abril-Pla ([@OriolAbril](https://github.com/OriolAbril))

‎docs/user_guide.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -166,3 +166,30 @@ Two command line options can help addressing these errors gradually:
166166
> [!TIP]
167167
> If you are trying out docstub and have feedback or problems, we'd love to hear from you!
168168
> Feel welcome to [open an issue](https://github.com/scientific-python/docstub/issues/new/choose). 🚀
169+
170+
171+
## Dealing with typing problems
172+
173+
Docstub may not fully or correctly implement a particular part of Python's typing system yet.
174+
175+
In some cases, you can use a comment directive to selectively disable docstub for a specific block of lines:
176+
```python
177+
class Foo:
178+
# docstub: off
179+
a: int = None
180+
b: str = ""
181+
# docstub: on
182+
c: int = None
183+
d: str = ""
184+
```
185+
will leave the parameters within the `# docstub` guards untouched in the resulting stub file:
186+
```python
187+
class Foo:
188+
a: int = None
189+
b: str = ""
190+
c: int
191+
d: str
192+
```
193+
194+
If that is not possible, you can – for now – fallback to writing a correct stub file by hand.
195+
Docstub will preserve this file and integrated it with other automatically generated stubs.

‎pyproject.toml

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,26 +4,27 @@ build-backend = "setuptools.build_meta"
44

55
[project]
66
name = "docstub"
7-
authors = [
7+
maintainers = [
88
{name = "Lars Grüter"},
99
]
1010
description = "Generate Python stub files from docstrings"
1111
readme = "README.md"
12-
license.file = "LICENSE"
12+
license = {file = "LICENSE"}
1313
requires-python = ">=3.12"
1414
classifiers = [
15-
"Development Status :: 1 - Planning",
15+
"Development Status :: 3 - Alpha",
16+
"Environment :: Console",
1617
"Intended Audience :: Developers",
18+
"Intended Audience :: Science/Research",
1719
"License :: OSI Approved :: BSD License",
1820
"Operating System :: OS Independent",
1921
"Programming Language :: Python",
2022
"Programming Language :: Python :: 3",
2123
"Programming Language :: Python :: 3 :: Only",
22-
"Programming Language :: Python :: 3.10",
23-
"Programming Language :: Python :: 3.11",
2424
"Programming Language :: Python :: 3.12",
25+
"Programming Language :: Python :: 3.13",
26+
"Topic :: Software Development :: Code Generators",
2527
"Topic :: Scientific/Engineering",
26-
"Typing :: Typed",
2728
]
2829
dynamic = ["version"]
2930
dependencies = [
@@ -104,6 +105,16 @@ testpaths = [
104105
[tool.coverage]
105106
run.source = ["docstub"]
106107

108+
109+
[tool.changelist.label_section_map]
110+
".*enhancement.*" = "Enhancement"
111+
".*performance.*" = "Performance"
112+
".*fix.*" = "Bug Fixes"
113+
".*documentation.*" = "Documentation"
114+
".*devops.*" = "DevOps"
115+
".*maintenance.*" = "Maintenance"
116+
117+
107118
[tool.docstub.types]
108119
Path = "pathlib"
109120

0 commit comments

Comments
 (0)