Add basic CI configuration (#8)

* Add basic CI configuration

* Use Python 3.12 as lowest bound in test matrix

* Shrink test matrix

No need to be wasteful.

* Include pytest-cov

* Fix paths and other tweaks

* Report positive comparison with example stubs

* Fix tool.docstub section

Got scrambled by an earlier partial commit.

* Add basic statistics

* Use "~" in doctype of Py2StubTransformer

* Use correct config file for example_pkg

* Match editable and normal install for test coverage

* Don't upload docstub-stubs

These multiple jobs conflict and I have no real use for these right
now.

Author: lagru

.github/workflows/ci.yml

@@ -0,0 +1,74 @@
+name: CI
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+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:
+  pre-commit:
+    name: pre-commit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - uses: pre-commit/action@v3.0.1
+        with:
+          extra_args: --hook-stage manual --all-files
+
+  checks:
+    name: Test on ${{ matrix.runs-on }} Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.runs-on }}
+    needs: [pre-commit]
+    strategy:
+      fail-fast: false
+      matrix:
+        runs-on: [ubuntu-latest, windows-latest, macos-14]
+        python-version: ["3.12"]
+
+        include:
+          - runs-on: ubuntu-latest
+            python-version: "3.13"
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+
+      - name: Install package
+        run: python -m pip install .[test,optional]
+
+      - name: Run pytest
+        run: >-
+          python -m pytest --showlocals -ra --cov --cov-report=term
+
+      # TODO upload coverage statistics, and fail on decrease?
+
+      - name: Compare example stubs
+        run: |
+          python -m docstub -v --config=examples/docstub.toml examples/example_pkg
+          git diff --exit-code examples/ && echo "Stubs for example_pkg did not change"
+
+      - name: Generate docstub stubs
+        run: |
+          python -m docstub -v src/docstub

README.md

@@ -20,9 +20,10 @@ pip install 'docstub [optional] @ git+https://github.com/scientific-python/docst
 ## Usage & configuration
 
 ```shell
-docstub example/example_pkg/
+cd examples/
+docstub example_pkg/
 ```
-will create stub files for `example_pkg/` in `example/example_pkg-stubs/`.
+will create stub files for `example_pkg/` in `examples/example_pkg-stubs/`.
 For now, refer to `docstub --help` for more.
 
 

pyproject.toml

@@ -44,7 +44,7 @@ dev = [
 ]
 test = [
   "pytest >=5.0.0",
-  "coverage >=7.5.0",
+  "pytest-cov >= 5.0.0",
 ]
 
 [project.urls]
@@ -90,6 +90,9 @@ ignore = [
 ]
 
 
-[tool.docstub.docnames]
+[tool.coverage]
+run.source = ["docstub"]
+
+[tool.docstub.known_imports]
 cst = {import = "libcst", as="cst"}
 lark = {import = "lark"}

src/docstub/_cli.py

@@ -17,12 +17,11 @@
 logger = logging.getLogger(__name__)
 
 
-def _find_configuration(source_dir, config_path):
-    """Find and load configuration from multiple possible sources.
+def _load_configuration(config_path=None):
+    """Load and merge configuration from CWD and optional files.
 
     Parameters
     ----------
-    source_dir : Path
     config_path : Path
 
     Returns
@@ -31,13 +30,13 @@ def _find_configuration(source_dir, config_path):
     """
     config = Config.from_toml(Config.DEFAULT_CONFIG_PATH)
 
-    pyproject_toml = source_dir.parent / "pyproject.toml"
+    pyproject_toml = Path.cwd() / "pyproject.toml"
     if pyproject_toml.is_file():
         logger.info("using %s", pyproject_toml)
         add_config = Config.from_toml(pyproject_toml)
         config = config.merge(add_config)
 
-    docstub_toml = source_dir.parent / "docstub.toml"
+    docstub_toml = Path.cwd() / "docstub.toml"
     if docstub_toml.is_file():
         logger.info("using %s", docstub_toml)
         add_config = Config.from_toml(docstub_toml)
@@ -87,7 +86,7 @@ def main(source_dir, out_dir, config_path, verbose):
     _setup_logging(verbose=verbose)
 
     source_dir = Path(source_dir)
-    config = _find_configuration(source_dir, config_path)
+    config = _load_configuration(config_path)
 
     # Build map of known imports
     known_imports = common_known_imports()

src/docstub/_stubs.py

@@ -572,7 +572,7 @@ def _annotations_from_node(self, node):
 
         Returns
         -------
-        annotations : DocstringAnnotations
+        annotations : ~.DocstringAnnotations
         """
         annotations = None
         docstring = node.get_docstring()