diff --git a/sphinx/config.py b/sphinx/config.py index 553aa74d6..b9f29668e 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -56,7 +56,7 @@ def is_serializable(obj: Any) -> bool: class ENUM: - """represents the config value should be a one of candidates. + """Represents the candidates which a config value should be one of. Example: 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: """ - 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'] 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: - """This converts old styled source_suffix to new styled one. + """Convert old styled source_suffix to new styled one. * old style: str or list * 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. * 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 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: - """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) 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: - """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. """ 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], changed: Set[str], removed: Set[str]) -> Set[str]: """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 'index' not in app.project.docnames and