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:
"""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