IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Split options into groups with finer granularity

Browse Source
This commit is contained in:
Adam Turner 2023-12-27 00:56:13 +00:00
parent aea69ea6af
commit 16c13fcb4c
1 changed files with 24 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
sphinx/cmd/build.py
View File

@ -138,39 +138,42 @@ files can be built by specifying individual filenames.
""")) """))
parser.add_argument('--version', action='version', dest='show_version', parser.add_argument('--version', action='version', dest='show_version',
version='%%(prog)s %s' % __display_version__) version=f'%(prog)s {__display_version__}')
parser.add_argument('sourcedir', parser.add_argument('sourcedir', metavar='SOURCE_DIR',
help=__('path to documentation source files')) help=__('path to documentation source files'))
parser.add_argument('outputdir', parser.add_argument('outputdir', metavar='OUTPUT_DIR',
help=__('path to output directory')) help=__('path to output directory'))
parser.add_argument('filenames', nargs='*', parser.add_argument('filenames', nargs='*',
help=__('a list of specific files to rebuild. Ignored ' help=__('(optional) a list of specific files to rebuild. '
'if -a is specified')) 'Ignored if --write-all is specified'))
group = parser.add_argument_group(__('general options')) group = parser.add_argument_group(__('general options'))
group.add_argument('-b', '--builder', metavar='BUILDER', dest='builder', group.add_argument('-b', '--builder', metavar='BUILDER', dest='builder',
default='html', default='html',
help=__('builder to use (default: html)')) help=__("builder to use (default: 'html')"))
group.add_argument('-j', '--jobs', metavar='N', default=1, type=jobs_argument,
dest='jobs',
help=__('run in parallel with N processes, when possible. '
"'auto' uses the number of CPU cores"))
group.add_argument('-a', '--write-all', action='store_true', dest='force_all', group.add_argument('-a', '--write-all', action='store_true', dest='force_all',
help=__('write all files (default: only write new and ' help=__('write all files (default: only write new and '
'changed files)')) 'changed files)'))
group.add_argument('-E', '--fresh-env', action='store_true', dest='freshenv', group.add_argument('-E', '--fresh-env', action='store_true', dest='freshenv',
help=__("don't use a saved environment, always read " help=__("don't use a saved environment, always read "
'all files')) 'all files'))
group = parser.add_argument_group(__('path options'))
group.add_argument('-d', '--doctree-dir', metavar='PATH', dest='doctreedir', group.add_argument('-d', '--doctree-dir', metavar='PATH', dest='doctreedir',
help=__('path for the cached environment and doctree ' help=__('directory for doctree and environment files '
'files (default: OUTPUTDIR/.doctrees)')) '(default: OUTPUT_DIR/.doctrees)'))
group.add_argument('-j', '--jobs', metavar='N', default=1, type=jobs_argument, group.add_argument('-c', '--conf-dir', metavar='PATH', dest='confdir',
dest='jobs', help=__('directory for the configuration file (conf.py) '
help=__('build in parallel with N processes where ' '(default: SOURCE_DIR)'))
'possible (special value "auto" will set N to cpu-count)'))
group = parser.add_argument_group('build configuration options') group = parser.add_argument_group('build configuration options')
group.add_argument('-c', '--config-dir', metavar='PATH', dest='confdir',
help=__('path where configuration file (conf.py) is '
'located (default: same as SOURCEDIR)'))
group.add_argument('-C', '--isolated', action='store_true', dest='noconfig', group.add_argument('-C', '--isolated', action='store_true', dest='noconfig',
help=__('use no config file at all, only -D options')) help=__('use no configuration file, only use settings from -D options'))
group.add_argument('-D', '--define', metavar='setting=value', action='append', group.add_argument('-D', '--define', metavar='setting=value', action='append',
dest='define', default=[], dest='define', default=[],
help=__('override a setting in configuration file')) help=__('override a setting in configuration file'))
@ -181,8 +184,7 @@ files can be built by specifying individual filenames.
dest='tags', default=[], dest='tags', default=[],
help=__('define tag: include "only" blocks with TAG')) help=__('define tag: include "only" blocks with TAG'))
group.add_argument('-n', '--nitpicky', action='store_true', dest='nitpicky', group.add_argument('-n', '--nitpicky', action='store_true', dest='nitpicky',
help=__('nit-picky mode, warn about all missing ' help=__('nit-picky mode: warn about all missing references'))
'references'))
group = parser.add_argument_group(__('console output options')) group = parser.add_argument_group(__('console output options'))
group.add_argument('-v', '--verbose', action='count', dest='verbosity', default=0, group.add_argument('-v', '--verbose', action='count', dest='verbosity', default=0,
@ -196,14 +198,15 @@ files can be built by specifying individual filenames.
help=__('do emit colored output (default: auto-detect)')) help=__('do emit colored output (default: auto-detect)'))
group.add_argument('-N', '--no-color', dest='color', action='store_const', group.add_argument('-N', '--no-color', dest='color', action='store_const',
const='no', const='no',
help=__('do not emit colored output (default: ' help=__('do not emit colored output (default: auto-detect)'))
'auto-detect)'))
group = parser.add_argument_group(__('warning control options'))
group.add_argument('-w', '--warning-file', metavar='FILE', dest='warnfile', group.add_argument('-w', '--warning-file', metavar='FILE', dest='warnfile',
help=__('write warnings (and errors) to given file')) help=__('write warnings (and errors) to given file'))
group.add_argument('-W', '--fail-on-warning', action='store_true', dest='warningiserror', group.add_argument('-W', '--fail-on-warning', action='store_true', dest='warningiserror',
help=__('turn warnings into errors')) help=__('turn warnings into errors'))
group.add_argument('--keep-going', action='store_true', dest='keep_going', group.add_argument('--keep-going', action='store_true', dest='keep_going',
help=__("with -W, keep going when getting warnings")) help=__("with --fail-on-warning, keep going when getting warnings"))
group.add_argument('-T', '--show-traceback', action='store_true', dest='traceback', group.add_argument('-T', '--show-traceback', action='store_true', dest='traceback',
help=__('show full traceback on exception')) help=__('show full traceback on exception'))
group.add_argument('-P', '--pdb', action='store_true', dest='pdb', group.add_argument('-P', '--pdb', action='store_true', dest='pdb',