CI: Bump tested Python version

.github/actions/setup/action.yml

@@ -0,0 +1,21 @@
+name: 'Default Checkout'
+description: 'checkout & setup'
+inputs:
+  python-version:
+    description: 'Python version'
+    required: true
+    default: '>=3'
+runs:
+  using: "composite"
+  steps:
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ inputs.python-version }}
+    - uses: actions/cache@v4
+      with:
+        path: |
+          ~/.cache/pip
+          ~\AppData\Local\pip\Cache
+          ~/Library/Caches/pip
+        key: ${{ runner.os }}-py${{ inputs.python-version }}

.github/workflows/ci.yml

@@ -2,72 +2,61 @@ name: CI
 on:
   push: { branches: [master] }
   pull_request: { branches: [master] }
-  schedule: [ cron: '12 2 * * 6' ]  # Every Saturday, 02:12
+  schedule: [ cron: '12 2 6 * *' ]
 
 jobs:
-  build:
-    name: Build
-    runs-on: ubuntu-18.04
-
-    strategy:
-      matrix:
-        python-version: [3.7, 3.8, '3.10']
-        include:
-          - python-version: 3.9
-            test-type: lint
-          - python-version: 3.9
-            test-type: docs
-
+  test-matrix:
+    runs-on: ubuntu-latest
     steps:
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: '>=3'
 
-      - uses: actions/cache@v2
-        name: Set up caches
-        with:
-          path: ~/.cache/pip
-          key: ${{ runner.os }}-py${{ matrix.python-version }}
+      - run: pip install -U pip setuptools wheel && pip install -U .
+      - run: time python -m unittest -v pdoc.test
 
-      - name: Checkout repo
-        uses: actions/checkout@v2
+  lint-test-coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
         with:
-          fetch-depth: 3
-      - name: Fetch tags
-        run: git fetch --depth=1 origin +refs/tags/*:refs/tags/*
+          fetch-depth: 2  # For codecov
+      - uses: ./.github/actions/setup
+        with:
+          python-version: 3.11
 
-      - name: Install dependencies
-        run: |
-          pip install -U pip setuptools wheel
-          pip install -U .
+      - run: pip install -U pip setuptools wheel && pip install -U .
 
       - name: Install lint dependencies
-        if: matrix.test-type == 'lint'
         run: |
           pip install flake8 coverage mypy types-Markdown
           sudo apt update && sudo apt-get install \
             texlive-xetex lmodern texlive-fonts-recommended  # test_pdf_pandoc
-          wget -O/tmp/pandoc.deb https://github.com/jgm/pandoc/releases/download/2.10/pandoc-2.10-1-amd64.deb && sudo dpkg -i /tmp/pandoc.deb
-
-      - name: Install docs dependencies
-        if: matrix.test-type == 'docs'
-        run: pip install -e .
+          wget -O/tmp/pandoc.deb https://github.com/jgm/pandoc/releases/download/3.1.12.2/pandoc-3.1.12.2-1-amd64.deb && sudo dpkg -i /tmp/pandoc.deb
+
+      - run: find -name '*.md' | xargs .github/lint-markdown.sh
+      - run: flake8 pdoc setup.py
+      - run: mypy -p pdoc
+      - run: time coverage run -m unittest -v pdoc.test
+      - run: bash <(curl -s https://codecov.io/bash)
+      - run: coverage report
+      - run: PDOC_TEST_PANDOC=1 time python -m unittest -v pdoc.test.CliTest.test_pdf_pandoc
+      - uses: actions/upload-artifact@v3
+        with:
+          name: Pdoc Documentation.pdf
+          path: /tmp/pdoc.pdf
 
-      - name: Test w/ Coverage, Lint
-        if: matrix.test-type == 'lint'
-        run: |
-          find -name '*.md' | xargs .github/lint-markdown.sh
-          flake8
-          mypy -p pdoc
-          time coverage run -m unittest -v pdoc.test
-          PDOC_TEST_PANDOC=1 time catchsegv python -m unittest -v pdoc.test.CliTest.test_pdf_pandoc
-          bash <(curl -s https://codecov.io/bash)
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup
+        with:
+          python-version: 3.11
 
-      - name: Test
-        if: '! matrix.test-type'
-        run: time python -m unittest -v pdoc.test
+      - name: Fetch tags
+        run: git fetch --depth=1 origin +refs/tags/*:refs/tags/*
 
-      - name: Test docs
-        if: matrix.test-type == 'docs'
-        run: time doc/build.sh
+      - run: pip install -U pip setuptools wheel && pip install -e .
+      - run: time doc/build.sh

README.md

@@ -8,7 +8,7 @@ pdoc
 [![package downloads](https://img.shields.io/pypi/dm/pdoc3.svg?color=skyblue&style=for-the-badge)](https://pypi.org/project/pdoc3)
 [![GitHub Sponsors](https://img.shields.io/github/sponsors/kernc?color=pink&style=for-the-badge)](https://github.com/sponsors/kernc)
 
-Auto-generate API documentation for Python projects.
+Auto-generate API documentation for Python 3+ projects.
 
 [**Project website**](https://pdoc3.github.io/pdoc/)
 

pdoc/__init__.py

@@ -267,7 +267,7 @@ def _pep224_docstrings(doc_obj: Union['Module', 'Class'], *,
             # Maybe raise exceptions with appropriate message
             # before using cleaned doc_obj.source
             _ = inspect.findsource(doc_obj.obj)
-            tree = ast.parse(doc_obj.source)  # type: ignore
+            tree = ast.parse(doc_obj.source)
         except (OSError, TypeError, SyntaxError) as exc:
             # Don't emit a warning for builtins that don't have source available
             is_builtin = getattr(doc_obj.obj, '__module__', None) == 'builtins'
@@ -345,7 +345,7 @@ def get_name(assign_node):
         def get_indent(line):
             return len(line) - len(line.lstrip())
 
-        source_lines = doc_obj.source.splitlines()  # type: ignore
+        source_lines = doc_obj.source.splitlines()
         assign_line = source_lines[assign_node.lineno - 1]
         assign_indent = get_indent(assign_line)
         comment_lines = []
@@ -451,7 +451,7 @@ def _toposort(graph: Mapping[T, Set[T]]) -> Generator[T, None, None]:
     assert not graph, f"A cyclic dependency exists amongst {graph!r}"
 
 
-def link_inheritance(context: Context = None):
+def link_inheritance(context: Optional[Context] = None):
     """
     Link inheritance relationsships between `pdoc.Class` objects
     (and between their members) of all `pdoc.Module` objects that
@@ -491,7 +491,7 @@ class Doc:
     """
     __slots__ = ('module', 'name', 'obj', 'docstring', 'inherits')
 
-    def __init__(self, name: str, module, obj, docstring: str = None):
+    def __init__(self, name: str, module, obj, docstring: str = ''):
         """
         Initializes a documentation object, where `name` is the public
         identifier name, `module` is a `pdoc.Module` object where raw
@@ -566,7 +566,7 @@ def qualname(self) -> str:
         return getattr(self.obj, '__qualname__', self.name)
 
     @lru_cache()
-    def url(self, relative_to: 'Module' = None, *, link_prefix: str = '',
+    def url(self, relative_to: Optional['Module'] = None, *, link_prefix: str = '',
             top_ancestor: bool = False) -> str:
         """
         Canonical relative URL (including page fragment) for this
@@ -624,8 +624,10 @@ class Module(Doc):
     __slots__ = ('supermodule', 'doc', '_context', '_is_inheritance_linked',
                  '_skipped_submodules')
 
-    def __init__(self, module: Union[ModuleType, str], *, docfilter: Callable[[Doc], bool] = None,
-                 supermodule: 'Module' = None, context: Context = None,
+    def __init__(self, module: Union[ModuleType, str], *,
+                 docfilter: Optional[Callable[[Doc], bool]] = None,
+                 supermodule: Optional['Module'] = None,
+                 context: Optional[Context] = None,
                  skip_errors: bool = False):
         """
         Creates a `Module` documentation object given the actual
@@ -1010,7 +1012,7 @@ class Class(Doc):
     """
     __slots__ = ('doc', '_super_members')
 
-    def __init__(self, name: str, module: Module, obj, *, docstring: str = None):
+    def __init__(self, name: str, module: Module, obj, *, docstring: Optional[str] = None):
         assert inspect.isclass(obj)
 
         if docstring is None:
@@ -1317,7 +1319,7 @@ class Function(Doc):
     """
     __slots__ = ('cls',)
 
-    def __init__(self, name: str, module: Module, obj, *, cls: Class = None):
+    def __init__(self, name: str, module: Module, obj, *, cls: Optional[Class] = None):
         """
         Same as `pdoc.Doc`, except `obj` must be a
         Python function object. The docstring is gathered automatically.
@@ -1419,7 +1421,8 @@ def return_annotation(self, *, link=None) -> str:
             s = re.sub(r'[\w\.]+', partial(_linkify, link=link, module=self.module), s)
         return s
 
-    def params(self, *, annotate: bool = False, link: Callable[[Doc], str] = None) -> List[str]:
+    def params(self, *, annotate: bool = False,
+               link: Optional[Callable[[Doc], str]] = None) -> List[str]:
         """
         Returns a list where each element is a nicely formatted
         parameter of this function. This includes argument lists,
@@ -1589,7 +1592,7 @@ class Variable(Doc):
     __slots__ = ('cls', 'instance_var')
 
     def __init__(self, name: str, module: Module, docstring, *,
-                 obj=None, cls: Class = None, instance_var: bool = False):
+                 obj=None, cls: Optional[Class] = None, instance_var: bool = False):
         """
         Same as `pdoc.Doc`, except `cls` should be provided
         as a `pdoc.Class` object when this is a class or instance

pdoc/cli.py

@@ -524,12 +524,13 @@ def main(_args=None):
             httpd.server_close()
             sys.exit(0)
 
-    docfilter = None
     if args.filter and args.filter.strip():
         def docfilter(obj, _filters=args.filter.strip().split(',')):
             return any(f in obj.refname or
                        isinstance(obj, pdoc.Class) and f in obj.doc
                        for f in _filters)
+    else:
+        docfilter = None
 
     modules = [pdoc.Module(module, docfilter=docfilter,
                            skip_errors=args.skip_errors)
@@ -592,7 +593,7 @@ def docfilter(obj, _filters=args.filter.strip().split(',')):
 pandoc --metadata=title:"MyProject Documentation"               \\
        --from=markdown+abbreviations+tex_math_single_backslash  \\
        --pdf-engine=xelatex --variable=mainfont:"DejaVu Sans"   \\
-       --toc --toc-depth=4 --output=pdf.pdf  pdf.md\
+       --toc --toc-depth=4 --output=/tmp/pdoc.pdf  pdf.md
 '''
 
 

pdoc/html_helpers.py

@@ -9,7 +9,7 @@
 import traceback
 from contextlib import contextmanager
 from functools import partial, lru_cache
-from typing import Callable, Match
+from typing import Callable, Match, Optional
 from warnings import warn
 import xml.etree.ElementTree as etree
 
@@ -408,8 +408,9 @@ def handleMatch(self, m, data):
 
 
 def to_html(text: str, *,
-            docformat: str = None,
-            module: pdoc.Module = None, link: Callable[..., str] = None,
+            docformat: Optional[str] = None,
+            module: Optional[pdoc.Module] = None,
+            link: Optional[Callable[..., str]] = None,
             latex_math: bool = False):
     """
     Returns HTML of `text` interpreted as `docformat`. `__docformat__` is respected
@@ -433,8 +434,9 @@ def to_html(text: str, *,
 
 
 def to_markdown(text: str, *,
-                docformat: str = None,
-                module: pdoc.Module = None, link: Callable[..., str] = None):
+                docformat: Optional[str] = None,
+                module: Optional[pdoc.Module] = None,
+                link: Optional[Callable[..., str]] = None):
     """
     Returns `text`, assumed to be a docstring in `docformat`, converted to markdown.
     `__docformat__` is respected

pdoc/test/__init__.py

@@ -70,10 +70,10 @@ def run(*args, **kwargs) -> int:
     params = list(filter(None, chain.from_iterable(params)))  # type: ignore
     _args = cli.parser.parse_args([*params, *args])           # type: ignore
     try:
-        returncode = cli.main(_args)
-        return returncode or 0
+        cli.main(_args)
+        return 0
     except SystemExit as e:
-        return e.code
+        return bool(e.code)
 
 
 @contextmanager
@@ -250,13 +250,13 @@ def test_html_ref_links(self):
             )
 
     def test_docformat(self):
-        with self.assertWarns(UserWarning) as cm,\
+        with self.assertWarns(UserWarning) as cm, \
                 run_html(EXAMPLE_MODULE, config='docformat="restructuredtext"'):
             self._basic_html_assertions()
         self.assertIn('numpy', cm.warning.args[0])
 
     def test_html_no_source(self):
-        with self.assertWarns(DeprecationWarning),\
+        with self.assertWarns(DeprecationWarning), \
                 run_html(EXAMPLE_MODULE, html_no_source=None):
             self._basic_html_assertions()
             self._check_files(exclude_patterns=['class="source"', 'Hidden'])
@@ -301,7 +301,7 @@ def test_external_links(self):
             self._basic_html_assertions()
             self._check_files(exclude_patterns=['<a href="/sys.version.ext"'])
 
-        with self.assertWarns(DeprecationWarning),\
+        with self.assertWarns(DeprecationWarning), \
                 run_html(EXAMPLE_MODULE, external_links=None):
             self._basic_html_assertions()
             self._check_files(['<a title="sys.version" href="/sys.version.ext"'])
@@ -319,7 +319,7 @@ def test_template_dir(self):
             pdoc.tpl_lookup._collection.clear()
 
     def test_link_prefix(self):
-        with self.assertWarns(DeprecationWarning),\
+        with self.assertWarns(DeprecationWarning), \
                 run_html(EXAMPLE_MODULE, link_prefix='/foobar/'):
             self._basic_html_assertions()
             self._check_files(['/foobar/' + EXAMPLE_MODULE])
@@ -417,7 +417,7 @@ def test_pdf_pandoc(self):
             run('pdoc', pdf=None)
             f.write(stdout.getvalue())
             subprocess.run(pdoc.cli._PANDOC_COMMAND, shell=True, check=True)
-            self.assertTrue(os.path.exists('pdf.pdf'))
+            self.assertTrue(os.path.exists('/tmp/pdoc.pdf'))
 
     def test_config(self):
         with run_html(EXAMPLE_MODULE, config='link_prefix="/foobar/"'):
@@ -445,8 +445,8 @@ def test_relative_dir_path(self):
                 self._check_files(())
 
     def test_skip_errors(self):
-        with chdir(os.path.join(TESTS_BASEDIR, EXAMPLE_MODULE, '_skip_errors')),\
-                redirect_streams(),\
+        with chdir(os.path.join(TESTS_BASEDIR, EXAMPLE_MODULE, '_skip_errors')), \
+                redirect_streams(), \
                 self.assertWarns(pdoc.Module.ImportWarning) as cm:
             run('.', skip_errors=None)
         self.assertIn('ZeroDivision', cm.warning.args[0])
@@ -953,7 +953,7 @@ def test_test_Function_params_python38_specific(self):
         self.assertEqual(func.params(), ['a', '/'])
 
     def test_Function_return_annotation(self):
-        def f() -> typing.List[typing.Union[str, pdoc.Doc]]: pass
+        def f() -> typing.List[typing.Union[str, pdoc.Doc]]: return []
         func = pdoc.Function('f', DUMMY_PDOC_MODULE, f)
         self.assertEqual(func.return_annotation(), 'List[Union[str,\N{NBSP}pdoc.Doc]]')