|
| 1 | +# Licensed under the GPL: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html |
| 2 | +# For details: https://github.com/pylint-dev/pylint/blob/main/LICENSE |
| 3 | +# Copyright (c) https://github.com/pylint-dev/pylint/blob/main/CONTRIBUTORS.txt |
| 4 | + |
| 5 | +"""Script used to generate the pyreverse configuration page.""" |
| 6 | + |
| 7 | +from __future__ import annotations |
| 8 | + |
| 9 | +from pathlib import Path |
| 10 | +from typing import NamedTuple |
| 11 | + |
| 12 | +from sphinx.application import Sphinx |
| 13 | + |
| 14 | +from pylint.pyreverse.main import OPTIONS_GROUPS, Run |
| 15 | +from pylint.typing import OptionDict |
| 16 | +from pylint.utils import get_rst_title |
| 17 | + |
| 18 | + |
| 19 | +class OptionsData(NamedTuple): |
| 20 | + name: str |
| 21 | + optdict: OptionDict |
| 22 | + |
| 23 | + |
| 24 | +PYREVERSE_PATH = ( |
| 25 | + Path(__file__).resolve().parent.parent / "additional_tools" / "pyreverse" |
| 26 | +) |
| 27 | +"""Path to the pyreverse documentation folder.""" |
| 28 | + |
| 29 | + |
| 30 | +def _write_config_page(run: Run) -> None: |
| 31 | + """Create or overwrite the configuration page.""" |
| 32 | + sections: list[str] = [ |
| 33 | + ".. This file is auto-generated. Make any changes to the associated\n" |
| 34 | + ".. docs extension in 'doc/exts/pyreverse_configuration.py'.\n\n", |
| 35 | + get_rst_title("Pyreverse Configuration", "^"), |
| 36 | + ] |
| 37 | + |
| 38 | + options: list[OptionsData] = [OptionsData(name, info) for name, info in run.options] |
| 39 | + option_groups: dict[str, list[str]] = {g: [] for g in OPTIONS_GROUPS.values()} |
| 40 | + |
| 41 | + for option in sorted(options, key=lambda x: x.name): |
| 42 | + option_string = get_rst_title(f"--{option.name}", '"') |
| 43 | + option_string += f"*{option.optdict.get('help')}*\n\n" |
| 44 | + |
| 45 | + if option.optdict.get("default") == "": |
| 46 | + option_string += '**Default:** ``""``\n\n\n' |
| 47 | + else: |
| 48 | + option_string += f"**Default:** ``{option.optdict.get('default')}``\n\n\n" |
| 49 | + |
| 50 | + option_groups[str(option.optdict.get("group"))].append(option_string) |
| 51 | + |
| 52 | + for group_title in OPTIONS_GROUPS.values(): |
| 53 | + sections.append( |
| 54 | + get_rst_title(group_title, "-") + "\n" + "".join(option_groups[group_title]) |
| 55 | + ) |
| 56 | + |
| 57 | + # Join all sections and remove the final two newlines |
| 58 | + final_page = "\n\n".join(sections)[:-2] |
| 59 | + |
| 60 | + with open(PYREVERSE_PATH / "configuration.rst", "w", encoding="utf-8") as stream: |
| 61 | + stream.write(final_page) |
| 62 | + |
| 63 | + |
| 64 | +# pylint: disable-next=unused-argument |
| 65 | +def build_options_page(app: Sphinx | None) -> None: |
| 66 | + # Write configuration page |
| 67 | + _write_config_page(Run([])) |
| 68 | + |
| 69 | + |
| 70 | +def setup(app: Sphinx) -> dict[str, bool]: |
| 71 | + """Connects the extension to the Sphinx process.""" |
| 72 | + # Register callback at the builder-inited Sphinx event |
| 73 | + # See https://www.sphinx-doc.org/en/master/extdev/appapi.html |
| 74 | + app.connect("builder-inited", build_options_page) |
| 75 | + return {"parallel_read_safe": True} |
0 commit comments