Merge branch 'master' into 295-184-reparenting-rework

.github/workflows/pydoctor_primer.yaml

@@ -0,0 +1,117 @@
+name: Run pydoctor_primer
+
+on:
+  # Only run on PR, since we diff against master
+  pull_request:
+    paths-ignore:
+    - 'pydoctor/test/**'
+    - 'docs/**'
+    - '*.rst'
+    - '*.txt'
+    - '*.in'
+    - '*.md'
+    - '.*'
+    - 'setup.py'
+
+
+jobs:
+  pydoctor_primer:
+    name: Run pydoctor_primer
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: pydoctor_to_test
+          fetch-depth: 0
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+      - name: Install pydoctor_primer
+        run: |
+          python -m pip install -U pip
+          pip install git+https://github.com/twisted/pydoctor_primer.git
+      - name: Run pydoctor_primer
+        shell: bash
+        run: |
+          cd pydoctor_to_test
+          echo "new commit"
+          git rev-list --format=%s --max-count=1 $GITHUB_SHA
+
+          MERGE_BASE=$(git merge-base $GITHUB_SHA origin/$GITHUB_BASE_REF)
+          git checkout -b base_commit $MERGE_BASE
+          echo "base commit"
+          git rev-list --format=%s --max-count=1 base_commit
+
+          echo ''
+          cd ..
+          # fail action if exit code isn't zero or one
+          (
+            pydoctor_primer \
+            --repo pydoctor_to_test \
+            --new $GITHUB_SHA --old base_commit \
+            --debug \
+            --output concise \
+            -j 8 \
+            | tee diff.txt
+          ) || [ $? -eq 1 ]
+
+      - name: Post comment
+        id: post-comment
+        uses: actions/github-script@v6
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const MAX_CHARACTERS = 30000
+            const MAX_CHARACTERS_PER_PROJECT = MAX_CHARACTERS / 3
+
+            const fs = require('fs')
+            let data = fs.readFileSync('diff.txt', { encoding: 'utf8' })
+
+            function truncateIfNeeded(original, maxLength) {
+              if (original.length <= maxLength) {
+                return original
+              }
+              let truncated = original.substring(0, maxLength)
+              // further, remove last line that might be truncated
+              truncated = truncated.substring(0, truncated.lastIndexOf('\n'))
+              let lines_truncated = original.split('\n').length - truncated.split('\n').length
+              return `${truncated}\n\n... (truncated ${lines_truncated} lines) ...`
+            }
+
+            const projects = data.split('\n\n')
+            // don't let one project dominate
+            data = projects.map(project => truncateIfNeeded(project, MAX_CHARACTERS_PER_PROJECT)).join('\n\n')
+            // posting comment fails if too long, so truncate
+            data = truncateIfNeeded(data, MAX_CHARACTERS)
+
+            console.log("Diff from pydoctor_primer:")
+            console.log(data)
+
+            let body
+            if (data.trim()) {
+              body = 'Diff from [pydoctor_primer](https://github.com/tristanlatr/pydoctor_primer), showing the effect of this PR on open source code:\n```diff\n' + data + '```'
+            } else {
+              body = "According to [pydoctor_primer](https://github.com/tristanlatr/pydoctor_primer), this change doesn't affect pydoctor warnings on a corpus of open source code. ✅"
+            }
+            const ev = JSON.parse(
+              fs.readFileSync(process.env.GITHUB_EVENT_PATH, 'utf8')
+            )
+            const prNumber = ev.pull_request.number
+
+            await github.rest.issues.createComment({
+              issue_number: prNumber,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body
+            })
+            return prNumber
+
+      - name: Hide old comments
+        uses: kanga333/[email protected]
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          leave_visible: 1
+          issue_number: ${{ steps.post-comment.outputs.result }}

README.rst

@@ -82,6 +82,12 @@ This is the last major release to support Python 3.7.
 * Add support for Python 3.12
 * `ExtRegistrar.register_post_processor()` now supports a `priority` argument that is an int.
   Highest priority callables will be called first during post-processing.
+* Fix too noisy ``--verbose`` mode (suppres some ambiguous annotations warnings).
+
+pydoctor 23.9.1
+^^^^^^^^^^^^^^^
+
+* Fix regression in link not found warnings' line numbers.
 
 pydoctor 23.9.0
 ^^^^^^^^^^^^^^^

pydoctor/linker.py

@@ -252,8 +252,6 @@ def __init__(self, obj:'model.Documentable') -> None:
         self._scope = obj.parent or obj
         self._module_linker = self._module.docstring_linker
         self._scope_linker = self._scope.docstring_linker
-
-        self.switch_context(obj).__enter__()
 
     @property
     def obj(self) -> 'model.Documentable':
@@ -263,24 +261,26 @@ def warn_ambiguous_annotation(self, target:str) -> None:
         # report a low-level message about ambiguous annotation
         mod_ann = self._module.expandName(target)
         obj_ann = self._scope.expandName(target)
-        if mod_ann != obj_ann:
+        if mod_ann != obj_ann and '.' in obj_ann and '.' in mod_ann:
             self.obj.report(
                 f'ambiguous annotation {target!r}, could be interpreted as '
                 f'{obj_ann!r} instead of {mod_ann!r}', section='annotation',
                 thresh=1
             )
 
     def link_to(self, target: str, label: "Flattenable") -> Tag:
-        if self._module.isNameDefined(target):
-            self.warn_ambiguous_annotation(target)
-            return self._module_linker.link_to(target, label)
-        elif self._scope.isNameDefined(target):
-            return self._scope_linker.link_to(target, label)
-        else:
-            return self._module_linker.link_to(target, label)
+        with self.switch_context(self._obj):
+            if self._module.isNameDefined(target):
+                self.warn_ambiguous_annotation(target)
+                return self._module_linker.link_to(target, label)
+            elif self._scope.isNameDefined(target):
+                return self._scope_linker.link_to(target, label)
+            else:
+                return self._module_linker.link_to(target, label)
 
     def link_xref(self, target: str, label: "Flattenable", lineno: int) -> Tag:
-        return self.obj.docstring_linker.link_xref(target, label, lineno)
+        with self.switch_context(self._obj):
+            return self.obj.docstring_linker.link_xref(target, label, lineno)
 
     @contextlib.contextmanager
     def switch_context(self, ob:Optional['model.Documentable']) -> Iterator[None]:

pydoctor/test/test_epydoc2stan.py

@@ -2120,3 +2120,46 @@ def func():
     assert docstring2html(mod.contents['func'], docformat='plaintext') == expected
     captured = capsys.readouterr().out
     assert captured == ''
+
+def test_regression_not_found_linenumbers(capsys: CapSys) -> None:
+    """
+    Test for issue https://github.com/twisted/pydoctor/issues/745
+    """
+    code = '''
+    __docformat__ = 'restructuredtext'
+    class Settings:
+        """
+        Object that manages the configuration for Twine.
+
+        This object can only be instantiated with keyword arguments.
+
+        For example,
+
+        .. code-block:: python
+
+            Settings(True, username='fakeusername')
+
+        Will raise a :class:`TypeError`. Instead, you would want
+
+        .. code-block:: python
+
+            Settings(sign=True, username='fakeusername')
+        """
+
+        def check_repository_url(self) -> None:
+            """
+            Verify we are not using legacy PyPI.
+            """
+            ...
+
+        def create_repository(self) -> repository.Repository:
+            """
+            Create a new repository for uploading.
+            """
+            ...
+    '''
+
+    mod = fromText(code, )
+    docstring2html(mod.contents['Settings'])
+    captured = capsys.readouterr().out
+    assert captured == '<test>:15: Cannot find link target for "TypeError"\n'