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

Fix doc build warning misattributions by upgrading Sphinx #1745

Merged
merged 1 commit into from
May 5, 2023

Conversation

pushfoo
Copy link
Member

@pushfoo pushfoo commented May 3, 2023

Changes

  • Update sphinx to 6.2.1 in pyproject.toml

Why

tl;dr

  1. Our current sphinx version does not correctly state the location of detected errors.
  2. I've run into this issue before
  3. At least one junior contributors has run into it in Minor improvements to GUI system #1690.
  4. sphinx==6.2.1 fixes this issue
  5. 6.2.1 is the last version before 7.0.0 makes breaking changes
  6. Nothing seems to be obviously broken when running doc build locally

Before upgrading Sphinx

This is the error output received in our CI:

Warning, treated as error:
/home/runner/work/arcade/arcade/arcade/gui/widgets/text.py:docstring of arcade.gui.widgets.text.UITextWidget:1:Block quote ends without a blank line; unexpected unindent.

However, there is no block quote in the top level docstring.

class UITextWidget(UIAnchorLayout):
    """
    Adds the ability to add text to a widget.

    The text can be placed within the widget using UIAnchorLayout parameters with `place_text()`.
    The text can be placed within the widget using
    :py:class:`~arcade.gui.UIAnchorLayout` parameters with
    :py:meth:`~arcade.gui.UITextWidget.place_text`.
    """

After upgrading Sphinx

Upgrading makes the location of the issue more legible:

/home/user/src/arcade/arcade/gui/widgets/text.py:docstring of arcade.gui.UITextWidget.multiline:4: WARNING: Block quote ends without a blank line; unexpected unindent.

At first glance, there doesn't seem to be anything immediately wrong. However, closer inspection allows us to understand it's the unescaped \n.

  @property
  def multiline(self):
      """
      Multiline state of the widget. Newlines indicated with ``\n`` will only
      be honored if this is set to true. If you want a scrollable text widget,
      use :py:class:`~arcade.gui.TextArea`.
      """
      return self.label.multiline

@einarf
Copy link
Member

einarf commented May 5, 2023

Let's just mere this.

@einarf einarf merged commit 3988d07 into pythonarcade:development May 5, 2023
5 checks passed
@pushfoo pushfoo deleted the upgrade_sphinx_to_6.2.1 branch May 7, 2023 06:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants