GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — gh-106948: Add Doc/nitpick_ignore.yml config file by vstinner · Pull Request #107278 · python/cpython

Conversation

@vstinner

@vstinner vstinner commented Jul 25, 2023 •
edited by github-actions Bot
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member

Maintaining nitpick_ignore Python list in conf.py is a burden. Add a YAML configuration file which is easier to maintain.

  • Issue: Docs: add standard external names to nitpick_ignore #106948

📚 Documentation preview 📚: https://cpython-previews--107278.org.readthedocs.build/

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
@bedevere-bot bedevere-bot mentioned this pull request Jul 25, 2023
Docs: add standard external names to nitpick_ignore #106948
Closed
@bedevere-bot bedevere-bot added the awaiting core review label Jul 25, 2023
@vstinner

vstinner commented Jul 25, 2023

Copy link
Copy Markdown
Member Author

I prefer YAML over TOML to write a list of strings with bare minimum formating: no quote, no [..., ..., ...]```, just a bullet point - ``.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@vstinner vstinner added the skip news label Jul 25, 2023
@vstinner
vstinner force-pushed the nitpick_ignore branch from 4a22872 to 133530d Compare July 25, 2023 23:47
@vstinner

vstinner commented Jul 25, 2023

Copy link
Copy Markdown
Member Author

cc @serhiy-storchaka @erlend-aasland @hugovk

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@vstinner
pythongh-106948: Add Doc/nitpick_ignore.yml config file
3f82400
Maintaining nitpick_ignore Python list in conf.py is a burden. Add a
YAML configuration file which is easier to maintain.

Ignore also standard C types in the "c:identifier" domain.

Update Doc/requirements-oldest-sphinx.txt.
@vstinner
vstinner force-pushed the nitpick_ignore branch from 133530d to 3f82400 Compare July 25, 2023 23:59
@AA-Turner

AA-Turner commented Jul 26, 2023

Copy link
Copy Markdown
Member

Cross-posting from discord: I’d prefer not to create an additional (CPython-custom) YAML file here if possible, perhaps instead we could have a nitpick_ignore.py that we just import into conf.py? I assume the objection to the variable being within conf.py is that the length makes the file unwieldy.

A

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@vstinner

vstinner commented Jul 26, 2023

Copy link
Copy Markdown
Member Author

I assume the objection to the variable being within conf.py is that the length makes the file unwieldy.

I would like to add a configuration file since writing a long list of strings in Python if annoying. The YAML file is less verbose.

Also, Standard C types (types section) is duplicated: used in the c:type domain and in the c:identifier domain.

Compare:

    ('c:func', 'calloc'),
    ('c:func', 'dlopen'),
    ('c:func', 'exec'),
    ('c:func', 'fcntl'),
    ('c:func', 'fork'),
    ('c:func', 'free'),
    ('c:func', 'gmtime'),

to:

  - calloc
  - dlopen
  - exec
  - fcntl
  - fork
  - free
  - gmtime
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@vstinner

vstinner commented Jul 26, 2023

Copy link
Copy Markdown
Member Author

Hum, shown diferently, I have a local branch to complete these nitpick ignore list. I added many functions, macros, etc. and the list is now quite big:

nitpick_ignore = [
    # Standard C macros
    ('c:macro', 'EDOM'),
    ('c:macro', 'EINTR'),
    ('c:macro', 'LLONG_MAX'),
    ('c:macro', 'LLONG_MIN'),
    ('c:macro', 'LONG_MAX'),
    ('c:macro', 'LONG_MIN'),
    ('c:macro', 'SIGINT'),
    # Standard C variables
    ('c:data', 'errno'),
    # Standard environment variables
    ('envvar', 'BROWSER'),
    ('envvar', 'COLUMNS'),
    ('envvar', 'COMSPEC'),
    ('envvar', 'DISPLAY'),
    ('envvar', 'HOME'),
    ('envvar', 'HOMEDRIVE'),
    ('envvar', 'HOMEPATH'),
    ('envvar', 'IDLESTARTUP'),
    ('envvar', 'LANG'),
    ('envvar', 'LANGUAGE'),
    ('envvar', 'LC_ALL'),
    ('envvar', 'LC_CTYPE'),
    ('envvar', 'LC_COLLATE'),
    ('envvar', 'LC_MESSAGES'),
    ('envvar', 'LC_MONETARY'),
    ('envvar', 'LC_NUMERIC'),
    ('envvar', 'LC_TIME'),
    ('envvar', 'LINES'),
    ('envvar', 'LOGNAME'),
    ('envvar', 'PAGER'),
    ('envvar', 'PATH'),
    ('envvar', 'PATHEXT'),
    ('envvar', 'SOURCE_DATE_EPOCH'),
    ('envvar', 'TEMP'),
    ('envvar', 'TERM'),
    ('envvar', 'TMP'),
    ('envvar', 'TMPDIR'),
    ('envvar', 'TZ'),
    ('envvar', 'USER'),
    ('envvar', 'USERNAME'),
    ('envvar', 'USERPROFILE'),
    # Win32 API
    ('c:func', 'FormatMessage'),
    ('c:func', 'GetFileInformationByHandle'),
    ('c:func', 'GetLastError'),
    ('c:func', 'GetVersionEx'),
    ('c:func', 'MessageBeep'),
    ('c:func', 'PlaySound'),
    ('c:func', 'ShellExecute'),
    ('c:func', 'TerminateProcess'),
    ('c:func', 'VirtualAlloc'),
    ('c:func', 'VirtualFree'),
    ('c:func', 'WSAIoctl'),
    # Win32 macros
    ('c:macro', 'CP_ACP'),
    # Do not error nit-picky mode builds when _SubParsersAction.add_parser cannot
    # be resolved, as the method is currently undocumented. For context, see
    # https://github.com/python/cpython/pull/103289.
    ('py:meth', '_SubParsersAction.add_parser'),
]

# Standard C types
c_std_types = """
FILE
__int64
int64_t
intmax_t
off_t
ptrdiff_t
siginfo_t
size_t
ssize_t
time_t
uint64_t
uintmax_t
uintptr_t
va_list
wchar
wchar_t
""".strip().split()

for name in c_std_types:
    nitpick_ignore.append(('c:type', name))
    # "c:identifier" domain is used by types in ".. c:function:" definitions
    nitpick_ignore.append(('c:identifier', name))

# Standard C functions
c_std_funcs = """
_exit
_stricmp
abort
atof
calloc
close
ctime
dlopen
exec
exit
fcntl
flock
fork
free
fstat
fsync
gettimeofday
getsid
gmtime
inet_aton
inet_pton
ioctl
localeconv
localtime
lockf
lstat
main
malloc
memmove
memcpy
mktime
mmap
munmap
open
perror
posix_spawn
posix_spawn_file_actions_addclose
posix_spawn_file_actions_adddup2
posix_spawn_file_actions_addopen
posix_spawnp
printf
putenv
qsort
realloc
select
setenv
setpgid
setpgrp
setsid
setsockopt
sigaction
sigaltstack
siginterrupt
signal
snprintf
splice
sprintf
stat
statvfs
strcasecmp
strcmp
strerror
strlen
strncmp
system
unsetenv
vsnprintf
vsprintf
""".strip().split()
for name in c_std_funcs:
    nitpick_ignore.append(('c:func', name))

Note: this list is incomplete :-)

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@vstinner vstinner mentioned this pull request Jul 26, 2023
Fix Sphinx warnings in C API doc #107274
Closed
@vstinner

vstinner commented Jul 26, 2023

Copy link
Copy Markdown
Member Author

This PR fix warnigs like:

c:identifier reference target not found: va_list

I get this warning more and more on PR changing the C API. Example in a PR changing the C API doc: https://github.com/python/cpython/pull/107274/files

Even if va_list is already in Doc/conf.py, the c:function markup looks for types in c:identifier and so emit a warning that the type is unknown. This PR adds va_list to c:type and c:identifier domains.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@hugovk

hugovk commented Jul 26, 2023

Copy link
Copy Markdown
Member

I've a slight (non-blocking) preference to avoid adding more code that needs maintaining, and having Sphinx deal with reading config.

Using standard Sphinx things also makes things more familiar for new contributors. And we're also cautious about adding new dependencies (PyYAML) in case downstream redistributors haven't installed them, for example, see sphinxext.opengraph.

I don't mind the existing nitpick_ignore list too much. Moving it to another Python file is okay too.

But it's more important to me to improve the docs, including fixing/ignoring warnings, so if others also like this approach, it's fine by me too.

erlend-aasland reacted with thumbs up emoji
All reactions
  • 👍 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@serhiy-storchaka

serhiy-storchaka commented Jul 26, 2023

Copy link
Copy Markdown
Member

It is a shame that Spjinx requires duplicating c:type names as c:identifier.

It can be fixed by a simple code:

for role, name in nitpick_ignore:
    if role == 'c:type':
        nitpick_ignore.append(('c:identifier', name))
del name, role

Would not it enough?

For now there is no significant difference between Python and YAML. Inany case we will add only few lines at once and not going to grow the nitpick_ignore list too much. Too much names here increase a chance of using incorrect role with a name from this list (it already happened with LINES and COLS).

erlend-aasland and CAM-Gerlach reacted with thumbs up emoji
All reactions
  • 👍 2 reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@vstinner

vstinner commented Jul 26, 2023

Copy link
Copy Markdown
Member Author

It is a shame that Spjinx requires duplicating c:type names as c:identifier. It can be fixed by a simple code: (...) Would not it enough?

I wrote PR #107295 to implement exactly that (I made minor changes in your proposed code).

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@vstinner

vstinner commented Jul 26, 2023

Copy link
Copy Markdown
Member Author

I abandon this PR in favor of PR #107295 (merged) and PR #107301. Thanks for your feedback.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@vstinner vstinner closed this Jul 26, 2023
@vstinner
vstinner deleted the nitpick_ignore branch July 26, 2023 17:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

awaiting core review skip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

5 participants

@vstinner @AA-Turner @hugovk @serhiy-storchaka @bedevere-bot
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.