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

Better sphinx.config docstrings

Browse Source
This commit is contained in:
Louis Maddox 2021-07-18 18:34:58 +01:00 committed by GitHub
parent efb6848ea9
commit b043e5b88d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 7 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
sphinx/config.py
View File

@ -56,7 +56,7 @@ def is_serializable(obj: Any) -> bool:
class ENUM: class ENUM:
"""represents the config value should be a one of candidates. """Represents the candidates which a config value should be one of.
Example: Example:
app.add_config_value('latex_show_urls', 'no', None, ENUM('no', 'footnote', 'inline')) app.add_config_value('latex_show_urls', 'no', None, ENUM('no', 'footnote', 'inline'))
@ -215,7 +215,7 @@ class Config:
def pre_init_values(self) -> None: def pre_init_values(self) -> None:
""" """
Initialize some limited config variables before initialize i18n and loading extensions Initialize some limited config variables before initializing i18n and loading extensions
""" """
variables = ['needs_sphinx', 'suppress_warnings', 'language', 'locale_dirs'] variables = ['needs_sphinx', 'suppress_warnings', 'language', 'locale_dirs']
for name in variables: for name in variables:
@ -343,7 +343,7 @@ def eval_config_file(filename: str, tags: Optional[Tags]) -> Dict[str, Any]:
def convert_source_suffix(app: "Sphinx", config: Config) -> None: def convert_source_suffix(app: "Sphinx", config: Config) -> None:
"""This converts old styled source_suffix to new styled one. """Convert old styled source_suffix to new styled one.
* old style: str or list * old style: str or list
* new style: a dict which maps from fileext to filetype * new style: a dict which maps from fileext to filetype
@ -371,7 +371,7 @@ def convert_highlight_options(app: "Sphinx", config: Config) -> None:
"""Convert old styled highlight_options to new styled one. """Convert old styled highlight_options to new styled one.
* old style: options * old style: options
* new style: dict that maps language names to options * new style: a dict which maps from language name to options
""" """
options = config.highlight_options options = config.highlight_options
if options and not all(isinstance(v, dict) for v in options.values()): if options and not all(isinstance(v, dict) for v in options.values()):
@ -392,7 +392,7 @@ def init_numfig_format(app: "Sphinx", config: Config) -> None:
def correct_copyright_year(app: "Sphinx", config: Config) -> None: def correct_copyright_year(app: "Sphinx", config: Config) -> None:
"""correct values of copyright year that are not coherent with """Correct values of copyright year that are not coherent with
the SOURCE_DATE_EPOCH environment variable (if set) the SOURCE_DATE_EPOCH environment variable (if set)
See https://reproducible-builds.org/specs/source-date-epoch/ See https://reproducible-builds.org/specs/source-date-epoch/
@ -405,7 +405,7 @@ def correct_copyright_year(app: "Sphinx", config: Config) -> None:
def check_confval_types(app: "Sphinx", config: Config) -> None: def check_confval_types(app: "Sphinx", config: Config) -> None:
"""check all values for deviation from the default value's type, since """Check all values for deviation from the default value's type, since
that can result in TypeErrors all over the place NB. that can result in TypeErrors all over the place NB.
""" """
for confval in config: for confval in config:
@ -469,7 +469,7 @@ def check_primary_domain(app: "Sphinx", config: Config) -> None:
def check_root_doc(app: "Sphinx", env: "BuildEnvironment", added: Set[str], def check_root_doc(app: "Sphinx", env: "BuildEnvironment", added: Set[str],
changed: Set[str], removed: Set[str]) -> Set[str]: changed: Set[str], removed: Set[str]) -> Set[str]:
"""Adjust root_doc to 'contents' to support an old project which does not have """Adjust root_doc to 'contents' to support an old project which does not have
no root_doc setting. any root_doc setting.
""" """
if (app.config.root_doc == 'index' and if (app.config.root_doc == 'index' and
'index' not in app.project.docnames and 'index' not in app.project.docnames and