Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Enhancement: Upgrade Sphinx version to eliminate incorrect syntax errors #947

Closed
4 tasks done
pushfoo opened this issue Sep 9, 2023 · 2 comments
Closed
4 tasks done
Labels
enhancement New feature or request

Comments

@pushfoo
Copy link
Contributor

pushfoo commented Sep 9, 2023

Older Sphinx versions, including pyglet's, do not report correct locations for syntax errors. Upgrading to 6.2.1 or later should fix some of the worst of these (see sphinx-doc/sphinx#11026).

Why this is relevant

  1. It's annoying when working on doc
  2. It has been discussed without objections before on Discord
  3. It delays PRs when people unfamiliar with the problem run into it (see this example from arcade)

For an example of how this affects our current code:

/home/pushfoo/src/pyglet/pyglet/graphics/shader.py:docstring of pyglet.graphics.shader.Attribute:1: WARNING: Definition list ends without a blank line; unexpected unindent.

However, there is no definition list at line 1 of Attribute's docstring:

class Attribute:
"""Abstract accessor for an attribute in a mapped buffer."""

Tasks required

To my understanding per prior discussion on Discord:

  • We're still on an old version because of our readthedocs config
  • Benjamin has no objections to upgrading as long as build keeps working

This implies we have to update the following:

  • Our sphinx version
    • Important note: Sphinx 7.2.0+ requires Python 3.9+, which can create an ugly situation for listing project requirements + readthedocs
  • Any incompatible plugins
  • Our readthedocs config
  • Any build scripts which need version bumps (I can't find any yet)
@pushfoo pushfoo added the enhancement New feature or request label Sep 9, 2023
@pushfoo
Copy link
Contributor Author

pushfoo commented Sep 13, 2023

Another benefit of using Sphinx 7.1+ is that we can show the full copyright list from LICENSE:

Changed in version 7.1: The value may now be a sequence of copyright statements in the above form, which will be displayed each to their own line.

@pushfoo
Copy link
Contributor Author

pushfoo commented Nov 30, 2023

Closing per Discord discussion and db94ffd

@pushfoo pushfoo closed this as completed Nov 30, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

1 participant