search

Chilipp / autodocsumm

Extending your autodoc API docs with a summary
Apache License 2.0
48 stars 14 forks source link

Allow Sphinx >=8.0 and fix deprecations; allow Python 3.12; rework test workflow #98

Closed theOehrly closed 2 months ago

theOehrly commented 2 months ago

This PR....

  1. ... allows using autodocsumm with Sphinx >= 8.0 and adresses the (single) relevant deprecation. I have read through the Sphinx changelog and there is nothing that looks problematic that hasn't come up in the tests.

  2. ... allows using autodocsumm with Python 3.12. There seems to be nothing preventing this. Tests are passing just fine.

  3. ... reworks the test workflow (a lot). The sphinxcontrib-* packages as well as the alabaster package have had new releases in the last few months. The newer versions of these packages now require specific minimum versions of Sphinx (only) at runtime using app.require_sphinx(). This means that pip is not able to resolve this (reverse) version constraint. Therefore, those packages need to be manually pinned to lower versions for older versions of Sphinx. As a result, the already complex version dependencies and pinning becomes even more convoluted. The new implementation is overall longer but much more explicit in defining the version combinations of Python, Sphinx and extra dependencies. Overall, this greatly improves the readability of what's going on here, in my opinion. I may have overdone it with the DRY principle by refactoring the actual test run steps into a separate workflow that is called from the various matrix combination steps. But I didn't just want to repeat those steps a bunch of times. As a result of these changes, the tested combinations of Python and Sphinx are not exactly equivalent to before. I took the following approach for defining the new test matrices:

    • test one release of each major Sphinx version at every supported Python version
    • AND for each Python version, test the latest Sphinx release that supports it
    • AND test the very latest Sphinx 8.x release at every supported Python version

Feel free to disagree with me on the workflow changes. Maybe this is a personal preference thing as well. But I really didn't want to add any more includes and excludes as well as conditionals for dependency versions.

The commits are intentionally left as they are to maybe make my chain of thought more understandable.

Closes #97

Chilipp commented 2 months ago

new release is out: https://pypi.org/project/autodocsumm/0.2.13/