Document and follow aliases better

.coveragerc

@@ -4,6 +4,7 @@ omit =
     pydoctor/sphinx_ext/*
     pydoctor/test/*
     pydoctor/epydoc/sre_parse36.py
+    pydoctor/epydoc/sre_constants36.py
 source =
     pydoctor
 

.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 }}

.github/workflows/system.yaml

@@ -12,20 +12,15 @@ jobs:
 
     strategy:
       matrix:
-        tox_target: [twisted-apidoc,
-                     cpython-summary, 
-                     python-igraph-apidocs, 
-                     cpython-apidocs,
-                     numpy-apidocs,
-                     git-buildpackage-apidocs,]
+        tox_target: [twisted-apidoc, cpython-summary, python-igraph-apidocs, cpython-apidocs, numpy-apidocs, git-buildpackage-apidocs, pytype-apidocs]
 
     steps:
     - uses: actions/checkout@v2
 
-    - name: Set up Python
+    - name: Set up CPython
       uses: actions/setup-python@v2
       with:
-        python-version: '3.8'
+        python-version: '3.11'
 
     - name: Install tox
       run: |
@@ -41,3 +36,4 @@ jobs:
     - name: Generate API docs
       run: |
         tox -e ${{ matrix.tox_target }}
+

.github/workflows/unit.yaml

@@ -14,13 +14,13 @@ jobs:
 
     strategy:
       matrix:
-        python-version: [3.6, 3.7, 3.8, 3.9, 3.10.0, pypy-3.6]
+        python-version: [pypy-3.7, 3.7, 3.8, 3.9, '3.10', 3.11, '3.12.0-rc.3']
         os: [ubuntu-20.04]
         include:
           - os: windows-latest
-            python-version: 3.6
+            python-version: 3.7
           - os: macos-latest
-            python-version: 3.6
+            python-version: 3.7
 
     steps:
     - uses: actions/checkout@v2
@@ -45,8 +45,8 @@ jobs:
       run: |
         tox -e test
 
-    - name: Run unit tests with latest Twisted version
-      if: matrix.python-version != '3.6' && matrix.python-version != 'pypy-3.6'
+    - name: Run unit tests with latest Twisted version (only for python 3.8 and later)
+      if: matrix.python-version != '3.7' && matrix.python-version != 'pypy-3.7'
       run: |
         tox -e test-latest-twisted
 

README.rst

@@ -4,8 +4,8 @@ pydoctor
 .. image:: https://img.shields.io/pypi/pyversions/pydoctor.svg
   :target: https://pypi.python.org/pypi/pydoctor
 
-.. image:: https://travis-ci.org/twisted/pydoctor.svg?branch=tox-travis-2
-  :target: https://travis-ci.org/twisted/pydoctor
+.. image:: https://github.com/twisted/pydoctor/actions/workflows/unit.yaml/badge.svg
+  :target: https://github.com/twisted/pydoctor/actions/workflows/unit.yaml
 
 .. image:: https://codecov.io/gh/twisted/pydoctor/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/twisted/pydoctor
@@ -76,6 +76,73 @@ What's New?
 in development
 ^^^^^^^^^^^^^^
 
+This is the last major release to support Python 3.7.
+
+* Drop support for Python 3.6
+* 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
+^^^^^^^^^^^^^^^
+
+This is the last major release to support Python 3.6.
+
+* Do not show `**kwargs` when keywords are specifically documented with the `keyword` field
+  and no specific documentation is given for the `**kwargs` entry.
+* Fix annotation resolution edge cases: names are resolved in the context of the module 
+  scope when possible, when impossible, the theoretical runtime scopes are used. A warning can
+  be reported when an annotation name is ambiguous (can be resolved to different names 
+  depending on the scope context) with option ``-v``.
+* Ensure that explicit annotation are honored when there are multiple declarations of the same name.
+* Use stricter verification before marking an attribute as constant: 
+   - instance variables are never marked as constant
+   - a variable that has several definitions will not be marked as constant
+   - a variable declaration under any kind of control flow block will not be marked as constant
+* Do not trigger warnings when pydoctor cannot make sense of a potential constant attribute 
+  (pydoctor is not a static checker).
+* Fix presentation of type aliases in string form.
+* Improve the AST colorizer to output less parenthesis when it's not required.
+* Fix colorization of dictionary unpacking.
+* Improve the class hierarchy such that it links top level names with intersphinx when possible.
+* Add highlighting when clicking on "View In Hierarchy" link from class page.
+* Recognize variadic generics type variables (PEP 646).
+* Fix support for introspection of cython3 generated modules.
+* Instance variables are marked as such across subclasses.
+
+pydoctor 23.4.1
+^^^^^^^^^^^^^^^
+
+* Pin ``urllib3`` version to keep compatibility with ``cachecontrol`` and python3.6.
+
+pydoctor 23.4.0
+^^^^^^^^^^^^^^^
+
+* Add support for Python 3.11
+* Add support for the ``@overload`` decorator.
+* Show type annotations in function's signatures.
+* If none of a function's parameters have documentation, do not render the parameter table.
+* Themes have been adjusted to render annotations more concisely.
+* Fix a rare crash in the type inference. 
+  Invalid python code like a set of lists would raise a uncaught TypeError in the evaluation.
+* Support when source path lies outside base directory (``--project-base-dir``).
+  Since pydoctor support generating docs for multiple packages, 
+  it is not certain that all of the source is even viewable below a single URL. 
+  We now allow to add arbitrary paths to the system, 
+  but only the objects inside a module wich path is relative to
+  the base directory can have a source control link generated.
+* Cache the default docutils settings on docutils>=0.19 to improve performance.
+* Improve the search bar user experience by automatically appending wildcard to each query terms
+  when no terms already contain a wildcard. 
+* Link recognized constructors in class page.
+* An invalid epytext docstring will be rederered as plaintext, just like invalid restructuredtext docstrings (finally).
+
 pydoctor 22.9.1
 ^^^^^^^^^^^^^^^
 * ``pydoctor --help`` works again.
@@ -109,7 +176,7 @@ pydoctor 22.7.0
 * Improve the extensibility of pydoctor (`more infos on extensions <https://pydoctor.readthedocs.io/en/latest/customize.html#use-a-custom-system-class>`_)
 * Fix line numbers in reStructuredText xref warnings.
 * Add support for `twisted.python.deprecated` (this was originally part of Twisted's customizations).
-* Add support for re-exporting it names imported from a wildcard import.
+* Add support for re-exporting names imported from a wildcard import.
 
 pydoctor 22.5.1
 ^^^^^^^^^^^^^^^

docs/epytext_demo/demo_epytext_module.py

@@ -6,7 +6,7 @@
 
 from abc import ABC
 import math
-from typing import AnyStr, Dict, Generator, List, Union, Callable, Tuple, TYPE_CHECKING
+from typing import overload, AnyStr, Dict, Generator, List, Union, Callable, Tuple, Sequence, Optional, Protocol, TYPE_CHECKING
 from somelib import SomeInterface
 import zope.interface
 import zope.schema
@@ -32,6 +32,9 @@
 This is also a constant, but annotated with typing.Final.
 """
 
+Interface = Protocol
+"""Aliases are also documented."""
+
 @deprecated(Version("demo", "NEXT", 0, 0), replacement=math.prod)
 def demo_product_deprecated(x, y) -> float: # type: ignore
     return float(x * y)
@@ -81,6 +84,26 @@ def demo_cross_reference() -> None:
         - L{Custom name <demo_typing_arguments>}
     """
 
+@overload
+def demo_overload(s: str) -> str:
+    ...
+
+@overload
+def demo_overload(s: bytes) -> bytes:
+    ...
+
+def demo_overload(s: Union[str, bytes]) -> Union[str, bytes]:
+    """
+    Overload signatures appear without the main signature and with C{@overload} decorator.
+
+    @param s: Some string or bytes param.
+    @return: Some string or bytes result.
+    """
+    raise NotImplementedError
+
+def demo_undocumented(s: str) -> str:
+    raise NotImplementedError
+
 
 class _PrivateClass:
     """

docs/restructuredtext_demo/demo_restructuredtext_module.py

@@ -8,7 +8,7 @@
 import math
 import zope.interface
 import zope.schema
-from typing import Callable, Sequence, Optional, AnyStr, Generator, Union, List, Dict, TYPE_CHECKING
+from typing import overload, Protocol, Callable, Sequence, Optional, AnyStr, Generator, Union, List, Dict, TYPE_CHECKING
 from incremental import Version
 from twisted.python.deprecate import deprecated, deprecatedProperty
 
@@ -30,6 +30,9 @@
 This is also a constant, but annotated with typing.Final.
 """
 
+Interface = Protocol
+"""Aliases are also documented."""
+
 @deprecated(Version("demo", "NEXT", 0, 0), replacement=math.prod)
 def demo_product_deprecated(x, y) -> float: # type: ignore
     return float(x * y)
@@ -89,6 +92,25 @@ def demo_cross_reference() -> None:
     - `demo_typing_arguments`
     """
 
+@overload
+def demo_overload(s: str) -> str:
+    ...
+
+@overload
+def demo_overload(s: bytes) -> bytes:
+    ...
+
+def demo_overload(s: Union[str, bytes]) -> Union[str, bytes]:
+    """
+    Overload signatures appear without the main signature and with ``@overload`` decorator.
+
+    :param s: Some string or bytes param.
+    :return: Some string or bytes result.
+    """
+    raise NotImplementedError
+
+def demo_undocumented(s: str) -> str:
+    raise NotImplementedError
 
 
 class _PrivateClass:
@@ -126,6 +148,7 @@ class DemoClass(ABC, _PrivateClass):
     .. versionchanged:: 1.2
         Add `read_and_write_delete` property.
     """
+    #FIXME: For some reason, the alias Demo do ont appear in the class page :/
 
     def __init__(self, one: str, two: bytes) -> None:
         """
@@ -180,6 +203,12 @@ def read_and_write_delete(self) -> None:
         """
         This is a docstring for deleter.
         """
+        pass
+
+    ro = read_only
+    rw = read_and_write
+    rwd = read_and_write_delete
+
 
 class IContact(zope.interface.Interface):
     """
@@ -196,3 +225,6 @@ class IContact(zope.interface.Interface):
 
     def send_email(text: str) -> None:
         pass
+
+_Demo = _PrivateClass
+Demo = DemoClass