Docstrings in configparser are invalid reStructuredText · Issue #100520 · python/cpython (original) (raw)

Skip to content

Navigation Menu

• • GitHub Copilot Write better code with AI
  • GitHub Advanced Security Find and fix vulnerabilities
  • Actions Automate any workflow
  • Codespaces Instant dev environments
  • Issues Plan and track work
  • Code Review Manage code changes
  • Discussions Collaborate outside of code
  • Code Search Find more, search less
• Explore
  • Learning Pathways
  • Events & Webinars
  • Ebooks & Whitepapers
  • Customer Stories
  • Partners
  • Executive Insights
• • GitHub Sponsors Fund open source developers
  • The ReadME Project GitHub community articles
• • Enterprise platform AI-powered developer platform
• Pricing

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Sign up

Description

In the configparser module, the docstrings are not valid rst. I stumbled onto this issue in the backport when I started validating documentation. Here's what the sphinx output looks like when trying to render the docs for that module:

docs: commands[0] /Users/jaraco/code/jaraco/configparser/docs> python -m sphinx -W --keep-going . /Users/jaraco/code/jaraco/configparser/build/html
Running Sphinx v5.3.0
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: [config changed ('project')] 2 added, 0 changed, 0 removed
reading sources... [100%] index                                                                                                                                    
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:22: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:22: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:26: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:30: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:33: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:37: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:44: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:48: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:88: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:88: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:103: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:103: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:103: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:103: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:136: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:9: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:5: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:8: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:8: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:8: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:7: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: Inline interpreted text or phrase reference start-string without end-string.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                                                                                                     
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: py:class reference target not found: backports.configparser.Error
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: py:class reference target not found: backports.configparser.Error
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: py:class reference target not found: backports.configparser.Error
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: py:class reference target not found: backports.configparser.Error
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: py:class reference target not found: backports.configparser.Error
/Users/jaraco/code/jaraco/configparser/src/backports/configparser/__init__.py:docstring of backports.configparser:1: WARNING: py:class reference target not found: backports.configparser.Error
generating indices... genindex py-modindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build finished with problems, 46 warnings.

It would be nice if the source documentation would compile nicely under sphinx without warnings.

Linked PRs

• gh-100520: Fix rst markup in configparser #100524
• [3.11] gh-100520: Fix rst markup in configparser docstrings (GH-100524) #100533
• [3.10] gh-100520: Fix rst markup in configparser docstrings (GH-100524) #100534