Automatically add a py.typed file alongside stubs (#98)

* Automatically add py.typed file to generated stubs

Remove docstub-stubs in CI before regenerating them. This tests that
the `py.typed` is actually regenerated by docstub.

* Add distribution section and mention py.typed in docs

* Avoid early exit in assert-unchanged.sh

and also show git status as a summary on failure.

* Add missing py.typed to example_pkg-stubs

* Also remove examples/example_pkg-stubs before regeneration

* Disable pip's progress bar during installation

Author: lagru

.github/scripts/assert-unchanged.sh

@@ -9,18 +9,19 @@ CHECK_DIR=$1
 
 # Find untracked files
 UNTRACKED=$(git ls-files --others --exclude-standard "$CHECK_DIR")
-# and display their content by comparing with '/dev/null'
-echo "$UNTRACKED" | xargs -I _ git --no-pager diff --no-index /dev/null _
+
+# Display diff of each untracked file by comparing with '/dev/null'
+# Hide exit code of `git diff` to avoid early exit due to `set -e`
+echo "$UNTRACKED" | xargs -I _ git --no-pager diff /dev/null _ || true
 
 # Display changes in tracked files and capture non-zero exit code if so
-set +e
-git diff --exit-code HEAD "$CHECK_DIR"
+git diff --exit-code HEAD "$CHECK_DIR" || true
 GIT_DIFF_HEAD_EXIT_CODE=$?
-set -e
 
 # Display changes in tracked files and capture exit status
 if [ $GIT_DIFF_HEAD_EXIT_CODE -ne 0 ] ||  [ -n "$UNTRACKED" ]; then
   echo "::error::Uncommited changes in directory '$CHECK_DIR'"
+  git status --porcelain
   exit 1
 else
   echo "::notice::No Uncommited changes, directory '$CHECK_DIR' is clean"

.github/workflows/ci.yml

@@ -17,6 +17,7 @@ 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
+  PIP_PROGRESS_BAR: "off"
 
 defaults:
   run:
@@ -81,6 +82,7 @@ jobs:
         # Check that stubs for example_pkg are up-to-date by regenerating them
         # with docstub and looking for differences.
         run: |
+          rm -rf examples/example_pkg-stubs
           python -m docstub run -v \
               --config=examples/docstub.toml \
               --out-dir=examples/example_pkg-stubs \
@@ -91,6 +93,7 @@ jobs:
         # Check that stubs for docstub are up-to-date by regenerating them
         # with docstub and looking for differences.
         run: |
+          rm -rf src/docstub-stubs
           python -m docstub run -v src/docstub -o src/docstub-stubs
           .github/scripts/assert-unchanged.sh src/docstub-stubs/
 

docs/introduction.md

@@ -204,3 +204,13 @@ class Foo:
 
 If all of the above does not solve your issue, you can fall back to writing a correct stub file by hand.
 Docstub will preserve this file and integrated it with other automatically generated stubs.
+
+
+## Distributing stub files
+
+The simplest option is to include generated stubs in the [distribution package](https://packaging.python.org/en/latest/glossary/#term-Distribution-Package) alongside your source files.
+For more complex setups please consult the official guide on [Packaging Type Information](https://typing.python.org/en/latest/spec/distributing.html#packaging-type-information).
+
+As required, Docstub will automatically place an empty `py.typed` file in the root directory of generated stubs to support type checking.
+If you need to [mark your stubs as partial](https://typing.python.org/en/latest/spec/distributing.html#partial-stub-packages), create the `py.typed` file beforehand.
+Docstub will not overwrite it.

examples/example_pkg-stubs/py.typed

@@ -399,6 +399,11 @@ def run(
             logger.info("Wrote %s", stub_path)
             fo.write(stub_content)
 
+    py_typed_out = out_dir / "py.typed"
+    if not py_typed_out.exists():
+        py_typed_out.touch()
+        logger.info("Created %s", py_typed_out)
+
     # Reporting --------------------------------------------------------------
 
     if group_errors: