Make --jobs a synonym for -j
#11210
Make --jobs a synonym for -j
#11210
Conversation
| @@ -151,6 +151,9 @@ Options | |||
| .. versionchanged:: 1.7 | |||
| Support ``auto`` argument. | |||
|
|
|||
| .. versionchanged:: 6.2 | |||
There was a problem hiding this comment.
versionadded or versionchanged?
6.1.4 or 6.2?
There was a problem hiding this comment.
On the former point, the Sphinx docs themselves are rather ambiguous, as for versionadded it says
This directive documents the version of the project which added the described feature to the library or C API. When this applies to an entire module, it should be placed at the top of the module section before any prose.
which implies that the directive should be an immediate child of the thing added. However, the example given is for a parameter, which doesn't have it's own scope and is instead manually called out in the descriptive text:
.. versionadded:: 2.5 The *spam* parameter.
And yet, the versionchanged description right below it includes "new parameters" as the first example of something a versionchanged directive would be used for instead of a versionadded (emphasis mine):
Similar to versionadded, but describes when and what changed in the named feature in some way (new parameters, changed side effects, etc.).
As for my take, I used to favor .. versionadded:: X.Y The <sub-thing> <sub-thing-type> as it was a little more concise to read and write, but my thinking has evolved to recommend `.. versionchanged`` instead as it is clearer and more semantically correct, and allows tools and Sphinx extensions (including one I'm building now) parsing the reST source, doctrees, etc to be able to determine unambiguously when a Sphinx-defined construct (function, class, method, struct member, option, etc) was added 1, It's also the usage I've generally seen in practice, at least in the Python docs and elsewhere.
Footnotes
-
Alternatively, for the latter you could rely on heuristics, e.g. don't assume the whole construct was added if the
versionaddedhas descriptive text, and potentially also parsing out parameters added from the description, but it's a lot less reliable, and a custom directive for added parameters (e.g... paramadded:: 3.12 spamis a much cleaner solution for that). ↩
There was a problem hiding this comment.
It is, to a great extent, up to the documenters. Even going by the Python documentation itself (as the most extensive example available), there's little consistency. For example, in the python command-line flags documentation, the documentation for the -X family of options documents the addition of each new -X arg arg as a versionadded... but the addition of the -X flag itself is documented as a versionchanged!! 😕
-XReserved for various implementation-specific options. CPython currently defines the following possible values:
-X faulthandlerto enable faulthandler;
-X showrefcountto output the total reference count and number of used memory blocks when the program finishes or after each statement in the interactive interpreter. This only works on debug builds.
-X tracemallocto start tracing Python memory allocations using the tracemalloc module. By default, only the most recent frame is stored in a traceback of a trace. Use -X tracemalloc=NFRAME to start tracing with a traceback limit of NFRAME frames. See the tracemalloc.start() for more information.
-X int_max_str_digitsconfigures the integer string conversion length limitation. See also PYTHONINTMAXSTRDIGITS.
-X importtimeto show how long each import takes. It shows module name, cumulative time (including nested imports) and self time (excluding nested imports). Note that its output may be broken in multi-threaded application. Typical usage is python3 -X importtime -c 'import asyncio'. See also PYTHONPROFILEIMPORTTIME.
-X dev: enable Python Development Mode, introducing additional runtime checks that are too expensive to be enabled by default.
-X utf8enables the Python UTF-8 Mode. -X utf8=0 explicitly disables Python UTF-8 Mode (even when it would otherwise activate automatically).
-X pycache_prefix=PATHenables writing .pyc files to a parallel tree rooted at the given directory instead of to the code tree. See also PYTHONPYCACHEPREFIX.
-X warn_default_encodingissues a EncodingWarning when the locale-specific default encoding is used for opening files. See also PYTHONWARNDEFAULTENCODING.
-X no_debug_rangesdisables the inclusion of the tables mapping extra location information (end line, start column offset and end column offset) to every instruction in code objects. This is useful when smaller code objects and pyc files are desired as well as suppressing the extra visual location indicators when the interpreter displays tracebacks. See also PYTHONNODEBUGRANGES.
-X frozen_modulesdetermines whether or not frozen modules are ignored by the import machinery. A value of “on” means they get imported and “off” means they are ignored. The default is “on” if this is an installed Python (the normal case). If it’s under development (running from the source tree) then the default is “off”. Note that the “importlib_bootstrap” and “importlib_bootstrap_external” frozen modules are always used, even if this flag is set to “off”.It also allows passing arbitrary values and retrieving them through the sys._xoptions dictionary.
Changed in version 3.2: The -X option was added.
New in version 3.3: The -X faulthandler option.
New in version 3.4: The -X showrefcount and -X tracemalloc options.
New in version 3.6: The -X showalloccount option.
New in version 3.7: The -X importtime, -X dev and -X utf8 options.
New in version 3.8: The -X pycache_prefix option. The -X dev option now logs close() exceptions in io.IOBase destructor.
Changed in version 3.9: Using -X dev option, check encoding and errors arguments on string encoding and decoding operations.
The -X showalloccount option has been removed.
New in version 3.10: The -X warn_default_encoding option.
Deprecated since version 3.9, removed in version 3.10: The -X oldparser option.
New in version 3.11: The -X no_debug_ranges option.
New in version 3.11: The -X frozen_modules option.
New in version 3.11: The -X int_max_str_digits option.
My take is, since only an alias is added, not warranting a new documentation section, then that only represents a change to the existing documentation for -j. (Now, -j/ --jobs.) So, yeah, +1 for versionchanged from me.
There was a problem hiding this comment.
Even going by the Python documentation itself (as the most extensive example available), there's little consistency.
Yeah, the Python docs are famously inconsistent on stuff like that. We're slowly working on it (though at least a little of it is my fault, since I used to use versionadded for that in the past).
| @@ -151,6 +151,9 @@ Options | |||
| .. versionchanged:: 1.7 | |||
| Support ``auto`` argument. | |||
|
|
|||
| .. versionchanged:: 6.2 | |||
There was a problem hiding this comment.
On the former point, the Sphinx docs themselves are rather ambiguous, as for versionadded it says
This directive documents the version of the project which added the described feature to the library or C API. When this applies to an entire module, it should be placed at the top of the module section before any prose.
which implies that the directive should be an immediate child of the thing added. However, the example given is for a parameter, which doesn't have it's own scope and is instead manually called out in the descriptive text:
.. versionadded:: 2.5 The *spam* parameter.
And yet, the versionchanged description right below it includes "new parameters" as the first example of something a versionchanged directive would be used for instead of a versionadded (emphasis mine):
Similar to versionadded, but describes when and what changed in the named feature in some way (new parameters, changed side effects, etc.).
As for my take, I used to favor .. versionadded:: X.Y The <sub-thing> <sub-thing-type> as it was a little more concise to read and write, but my thinking has evolved to recommend `.. versionchanged`` instead as it is clearer and more semantically correct, and allows tools and Sphinx extensions (including one I'm building now) parsing the reST source, doctrees, etc to be able to determine unambiguously when a Sphinx-defined construct (function, class, method, struct member, option, etc) was added 1, It's also the usage I've generally seen in practice, at least in the Python docs and elsewhere.
Footnotes
-
Alternatively, for the latter you could rely on heuristics, e.g. don't assume the whole construct was added if the
versionaddedhas descriptive text, and potentially also parsing out parameters added from the description, but it's a lot less reliable, and a custom directive for added parameters (e.g... paramadded:: 3.12 spamis a much cleaner solution for that). ↩
Subject: Add
--jobsto the Sphinx command-line optionsFeature or Bugfix
Purpose
--jobsas a synonym for the-jflag.Detail
--jobs. Compare withmake --help:Before
After
Relates