Prepare release of version 0.3.0

.github/workflows/cd.yml

@@ -0,0 +1,41 @@
+name: CD
+
+on:
+  workflow_dispatch:
+  release:
+    types:
+      - published
+
+
+env:
+  # Many color libraries just need this to be set to any value, but at least
+  # one distinguishes color depth, where "3" -> "256-bit color".
+  FORCE_COLOR: 3
+
+
+jobs:
+  pypi-publish:
+    name: Build & publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+      url: https://pypi.org/p/docstub
+    permissions:
+      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Build wheel & sdist
+        run: |
+          git clean -fxd
+          pip install -U build twine wheel
+          python -m build --sdist --wheel
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4

.github/workflows/ci.yml

@@ -47,7 +47,7 @@ jobs:
           - { short: linux, name: ubuntu-latest }
           - { short: win, name: windows-latest }
           - { short: macos, name: macos-14 }
-        python-version: ["3.12"]
+        python-version: ["3.12", "3.13"]
 
     steps:
       - uses: actions/checkout@v4

README.md

@@ -16,7 +16,7 @@ It does so by supporting widely used readable conventions such as `array of dtyp
 
 ## Installation & getting started
 
-Please refer to the [user guide](docs/user_guide.md) to get started with docstub.
+Please refer to the [user guide](https://github.com/scientific-python/docstub/blob/main/docs/user_guide.md) to get started with docstub.
 
 
 ## Contributing

docs/release_notes/v0.2.0.md

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

docs/release_notes/v0.3.0.md

@@ -0,0 +1,95 @@
+# docstub 0.3.0
+
+This release marks the first "Alpha" release of docstub. 🎉
+
+## Highlights
+
+- **A revamped command line interface**
+  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)).
+  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)).
+
+- **Improved error reporting and statistics**
+  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)).
+  Similarly, docstub will report the total number of errors, types that it didn't know where to import from and the total runtime.
+
+- **Improved typing support**
+  Module and class attributes can now be typed in docstrings too ([#18](https://github.com/scientific-python/docstub/pull/18)).
+  This includes support for the special case of dataclasses ([#26](https://github.com/scientific-python/docstub/pull/26)).
+  You can now document generator functions with the "Yields" and "Receives" docstring sections ([#29](https://github.com/scientific-python/docstub/pull/29)).
+  For edge cases, that docstub doesn't yet (correctly) support, you can now wrap lines in `# docstub: off` and `# docstub: on`.
+  This selectively prevents docstub from changing lines during stub creation ([#25](https://github.com/scientific-python/docstub/pull/25)).
+
+- **Improved configuration**
+  Simplified the configuration file.
+  Declaring external types should be a lot more straightforward.
+  A reference for the configuration file is scheduled for the next release ([#45](https://github.com/scientific-python/docstub/pull/45)).
+
+- 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)).
+
+Find a more detailed list of pull requests contributing to this release below.
+
+## Enhancement
+
+- Stub files are now created inplace if no explicit output directory is specified.
+  Pre-existing stub files that are not managed by docstub are preserved as before ([#28](https://github.com/scientific-python/docstub/pull/28)).
+- You can now indicate a plural with `(s)` in expressions like `list of int(s)`  ([#37](https://github.com/scientific-python/docstub/pull/37)).
+  The grammar supporting the typing syntax in docstring should be better behaved for edge cases now.
+- Collect docnames of analyzed source in advance ([#2](https://github.com/scientific-python/docstub/pull/2)).
+- Point to precise line in parsed source for parsing problems ([#10](https://github.com/scientific-python/docstub/pull/10)).
+- Support attributes and type aliases ([#18](https://github.com/scientific-python/docstub/pull/18)).
+- Add direct support for dataclasses ([#26](https://github.com/scientific-python/docstub/pull/26)).
+- Support Yields section and Generator functions ([#29](https://github.com/scientific-python/docstub/pull/29)).
+- Add `--group-errors` option ([#30](https://github.com/scientific-python/docstub/pull/30)).
+- Add `--allow-errors` command line option ([#32](https://github.com/scientific-python/docstub/pull/32)).
+- Support combined NumPyDoc params ([#41](https://github.com/scientific-python/docstub/pull/41)).
+
+## Bug Fixes
+
+- Only use `| None` for optional parameters if appropriate ([#14](https://github.com/scientific-python/docstub/pull/14)).
+- Check test suite with mypy ([#27](https://github.com/scientific-python/docstub/pull/27)).
+- fix check for length 1 literal ([#40](https://github.com/scientific-python/docstub/pull/40)).
+- Allow signed numbers in literals ([#46](https://github.com/scientific-python/docstub/pull/46)).
+
+## Performance
+
+- 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)).
+
+## Documentation
+
+- Attribute copyright to Scientific Python Developers ([#4](https://github.com/scientific-python/docstub/pull/4)).
+- Reword descriptions in manual ([#23](https://github.com/scientific-python/docstub/pull/23)).
+- Refactor and document doctype grammar ([#33](https://github.com/scientific-python/docstub/pull/33)).
+- Add minimal documentation ([#24](https://github.com/scientific-python/docstub/pull/24)).
+
+## Devops
+
+- Add basic CI configuration ([#8](https://github.com/scientific-python/docstub/pull/8)).
+- Enable doctests by default ([#12](https://github.com/scientific-python/docstub/pull/12)).
+- Use mypy.stubtest in CI ([#25](https://github.com/scientific-python/docstub/pull/25)).
+- Check test suite with mypy ([#27](https://github.com/scientific-python/docstub/pull/27)).
+- Check `tests/` with basedpyright in CI in "standard" mode ([#50](https://github.com/scientific-python/docstub/pull/50)).
+- Prepare release of version 0.3.0 ([#51](https://github.com/scientific-python/docstub/pull/51)).
+
+## Maintenance
+
+- Fix python_requires ([#5](https://github.com/scientific-python/docstub/pull/5)).
+- Refactor and document doctype grammar ([#33](https://github.com/scientific-python/docstub/pull/33)).
+- Update import for Generator and Callable types ([#34](https://github.com/scientific-python/docstub/pull/34)).
+- Refactor configuration fields ([#45](https://github.com/scientific-python/docstub/pull/45)).
+- Add minimal documentation ([#24](https://github.com/scientific-python/docstub/pull/24)).
+- Move main CLI functionality into `docstub run` subcommand ([#49](https://github.com/scientific-python/docstub/pull/49)).
+
+## Contributors
+
+3 authors added to this release (alphabetically):
+
+- Lars Grüter ([@lagru](https://github.com/lagru))
+- Marianne Corvellec ([@mkcor](https://github.com/mkcor))
+- Oriol Abril-Pla ([@OriolAbril](https://github.com/OriolAbril))
+
+4 reviewers added to this release (alphabetically):
+
+- Brigitta Sipőcz ([@bsipocz](https://github.com/bsipocz))
+- Lars Grüter ([@lagru](https://github.com/lagru))
+- Marianne Corvellec ([@mkcor](https://github.com/mkcor))
+- Oriol Abril-Pla ([@OriolAbril](https://github.com/OriolAbril))

docs/user_guide.md

@@ -166,3 +166,30 @@ Two command line options can help addressing these errors gradually:
 > [!TIP]
 > If you are trying out docstub and have feedback or problems, we'd love to hear from you!
 > Feel welcome to [open an issue](https://github.com/scientific-python/docstub/issues/new/choose). 🚀
+
+
+## Dealing with typing problems
+
+Docstub may not fully or correctly implement a particular part of Python's typing system yet.
+
+In some cases, you can use a comment directive to selectively disable docstub for a specific block of lines:
+```python
+class Foo:
+    # docstub: off
+    a: int = None
+    b: str = ""
+    # docstub: on
+    c: int = None
+    d: str = ""
+```
+will leave the parameters within the `# docstub` guards untouched in the resulting stub file:
+```python
+class Foo:
+    a: int = None
+    b: str = ""
+    c: int
+    d: str
+```
+
+If that is not possible, you can – for now – fallback to writing a correct stub file by hand.
+Docstub will preserve this file and integrated it with other automatically generated stubs.

pyproject.toml

@@ -4,26 +4,27 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "docstub"
-authors = [
+maintainers = [
   {name = "Lars Grüter"},
 ]
 description = "Generate Python stub files from docstrings"
 readme = "README.md"
-license.file = "LICENSE"
+license = {file = "LICENSE"}
 requires-python = ">=3.12"
 classifiers = [
-  "Development Status :: 1 - Planning",
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
   "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
   "License :: OSI Approved :: BSD License",
   "Operating System :: OS Independent",
   "Programming Language :: Python",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3 :: Only",
-  "Programming Language :: Python :: 3.10",
-  "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Code Generators",
   "Topic :: Scientific/Engineering",
-  "Typing :: Typed",
 ]
 dynamic = ["version"]
 dependencies = [
@@ -104,6 +105,16 @@ testpaths = [
 [tool.coverage]
 run.source = ["docstub"]
 
+
+[tool.changelist.label_section_map]
+".*enhancement.*" = "Enhancement"
+".*performance.*" = "Performance"
+".*fix.*" = "Bug Fixes"
+".*documentation.*" = "Documentation"
+".*devops.*" = "DevOps"
+".*maintenance.*" = "Maintenance"
+
+
 [tool.docstub.types]
 Path = "pathlib"