From 3145d3cdc7254c7ce0bf9c39fef0340971b4f98c Mon Sep 17 00:00:00 2001 From: Tim Paine <3105306+timkpaine@users.noreply.github.com> Date: Mon, 2 Feb 2026 15:58:04 -0500 Subject: [PATCH] Clean up and formalize more options --- yardang/build.py | 30 +++++++++++++---- yardang/conf.py.j2 | 81 +++++++++++++++++++++++++++++++++++++++------- 2 files changed, 93 insertions(+), 18 deletions(-) diff --git a/yardang/build.py b/yardang/build.py index ebc38eb..ddb5299 100644 --- a/yardang/build.py +++ b/yardang/build.py @@ -27,6 +27,7 @@ def generate_docs_configuration( cname: str = "", pages: Optional[List] = None, use_autoapi: Optional[bool] = None, + autoapi_ignore: Optional[List] = None, custom_css: Optional[Path] = None, custom_js: Optional[Path] = None, config_base: str = "tool.yardang", @@ -69,10 +70,26 @@ def generate_docs_configuration( cname = cname or get_config(section="cname", base=config_base) pages = pages or get_config(section="pages", base=config_base) or [] use_autoapi = use_autoapi or get_config(section="use-autoapi", base=config_base) + autoapi_ignore = autoapi_ignore or get_config(section="docs.autoapi-ignore") custom_css = custom_css or Path(get_config(section="custom-css", base=config_base) or (Path(__file__).parent / "custom.css")) custom_js = custom_js or Path(get_config(section="custom-js", base=config_base) or (Path(__file__).parent / "custom.js")) + # if custom_css and custom_js are strings and they exist as paths, read them as Paths + # otherwise, assume the content is directly provided + if isinstance(custom_css, str): + css_path = Path(custom_css) + if css_path.exists(): + custom_css = css_path.read_text() + elif isinstance(custom_css, Path): + custom_css = custom_css.read_text() + if isinstance(custom_js, str): + js_path = Path(custom_js) + if js_path.exists(): + custom_js = js_path.read_text() + elif isinstance(custom_js, Path): + custom_js = custom_js.read_text() + source_dir = os.path.curdir configuration_args = {} @@ -107,15 +124,15 @@ def generate_docs_configuration( "nb_execution_mode": "off", "nb_execution_excludepatterns": [], # autodoc/autodoc-pydantic - "autodoc_pydantic_model_show_config_summary": None, - "autodoc_pydantic_model_show_validator_summary": None, - "autodoc_pydantic_model_show_validator_members": None, "autodoc_pydantic_field_list_validators": None, "autodoc_pydantic_field_show_constraints": None, "autodoc_pydantic_model_member_order": "bysource", + "autodoc_pydantic_model_show_config_summary": None, + "autodoc_pydantic_model_show_field_summary": None, "autodoc_pydantic_model_show_json": True, + "autodoc_pydantic_model_show_validator_summary": None, + "autodoc_pydantic_model_show_validator_members": None, "autodoc_pydantic_settings_show_json": None, - "autodoc_pydantic_model_show_field_summary": None, # sphinx-reredirects "redirects": {}, }.items(): @@ -139,6 +156,7 @@ def generate_docs_configuration( cname=cname, pages=pages, use_autoapi=use_autoapi, + autoapi_ignore=autoapi_ignore, source_dir=source_dir, previous_versions=previous_versions, **configuration_args, @@ -164,9 +182,9 @@ def generate_docs_configuration( # write custom css and customjs Path("docs/html/_static/styles").mkdir(parents=True, exist_ok=True) - Path("docs/html/_static/styles/custom.css").write_text(custom_css.read_text()) + Path("docs/html/_static/styles/custom.css").write_text(custom_css) Path("docs/html/_static/js").mkdir(parents=True, exist_ok=True) - Path("docs/html/_static/js/custom.js").write_text(custom_js.read_text()) + Path("docs/html/_static/js/custom.js").write_text(custom_js) # append docs-specific ignores to gitignore if Path(".gitignore").exists(): diff --git a/yardang/conf.py.j2 b/yardang/conf.py.j2 index 28bd17c..543c290 100644 --- a/yardang/conf.py.j2 +++ b/yardang/conf.py.j2 @@ -1,8 +1,27 @@ +# / ____| ____| \ | | ____| __ \ /\|__ __| ____| __ \ +# | | __| |__ | \| | |__ | |__) | / \ | | | |__ | | | | +# | | |_ | __| | . ` | __| | _ / / /\ \ | | | __| | | | | +# | |__| | |____| |\ | |____| | \ \ / ____ \| | | |____| |__| | +# \_____|______|_| \_|______|_|_ \_\/_/ \_\_| |______|_____/ +# +# +# | __ \ | | | (_)/ _| +# | | | | ___ _ __ ___ | |_ _ __ ___ ___ __| |_| |_ _ _ +# | | | |/ _ \ | '_ \ / _ \| __| | '_ ` _ \ / _ \ / _` | | _| | | | +# | |__| | (_) | | | | | (_) | |_ | | | | | | (_) | (_| | | | | |_| | +# |_____/ \___/ |_| |_|\___/ \__| |_| |_| |_|\___/ \__,_|_|_| \__, | +# __/ | +# |___/ +# This file is not a real python file, it is a jinja template + import os import os.path from packaging.version import Version from pathlib import Path +######################## +# COMMON CONFIGURATION # +######################## project = "{{project}}" module = "{{module}}" name = "{{project}}" @@ -12,8 +31,6 @@ copyright = """{{copyright}}""" title = """{{title}}""" version = "{{version}}" release = "{{version}}" -html_title = """{{title}} v{{version}}""" docs_host_root = "{{docs_root}}" root = "{{root}}" @@ -25,9 +42,20 @@ pages = """ """ use_autoapi = {{use_autoapi}} # noqa: F821 -###################### -# Standardized below # -###################### +############################################################################################################# +# _____ _ _ _ __ _ _ # +# | __ \ | | | (_)/ _| | | | | # +# | | | | ___ _ __ ___ | |_ _ __ ___ ___ __| |_| |_ _ _ | |__ ___| | _____ __ # +# | | | |/ _ \ | '_ \ / _ \| __| | '_ ` _ \ / _ \ / _` | | _| | | | | '_ \ / _ \ |/ _ \ \ /\ / / # +# | |__| | (_) | | | | | (_) | |_ | | | | | | (_) | (_| | | | | |_| | | |_) | __/ | (_) \ V V / # +# |_____/ \___/ |_| |_|\___/ \__| |_| |_| |_|\___/ \__,_|_|_| \__, | |_.__/ \___|_|\___/ \_/\_/ # +# __/ | # +# |___/ # +############################################################################################################# + +################### +# BASE EXTENSIONS # +################### extensions = [ "myst_nb", "sphinx.ext.napoleon", @@ -53,8 +81,14 @@ else: # viewcode to come after extensions.append("sphinx.ext.viewcode") - +######### +# HOOKS # +######### os.environ["SPHINX_BUILDING"] = "1" + +############ +# THEMEING # +############ html_theme = "{{theme}}" html_theme_options = {{html_theme_options}} html_static_path = {{html_static_path}} @@ -67,6 +101,10 @@ html_js_files = [ *{{html_js_files}} ] +#################### +# SPHINX INTERNALS # +#################### + master_doc = "index" templates_path = ["_templates"] source_suffix = [".rst", ".md", *{{source_suffix}}] @@ -90,35 +128,55 @@ mermaid_include_zenuml = True redirects = {{redirects}} # autosummary -autosummary_generate = True +autosummary_generate = True # if using autosummary, autogenerate + +# autodoc/autoapi +autodoc_default_options = { + "exclude-members": "model_post_init", # https://github.com/mansenfranzen/autodoc_pydantic/issues/198 + "show-inheritance": True, +} # autoapi autoapi_dirs = [module] +autoapi_ignore = {{autoapi_ignore}} # noqa: F821 autoapi_python_class_content = "both" +# Turn off automatic autoapi as we will +# use both autoapi and autodoc autoapi_add_toctree_entry = use_autoapi is True # autodoc/autodoc-pydantic -autodoc_default_options = {"show-inheritance": True} -autodoc_pydantic_model_show_config_summary = {{autodoc_pydantic_model_show_config_summary}} # noqa: F821 -autodoc_pydantic_model_show_validator_summary = {{autodoc_pydantic_model_show_validator_summary}} # noqa: F821 -autodoc_pydantic_model_show_validator_members = {{autodoc_pydantic_model_show_validator_members}} # noqa: F821 +autodoc_default_options = { + "exclude-members": "model_post_init", # https://github.com/mansenfranzen/autodoc_pydantic/issues/198 + "show-inheritance": True, +} + autodoc_pydantic_field_list_validators = {{autodoc_pydantic_field_list_validators}} # noqa: F821 autodoc_pydantic_field_show_constraints = {{autodoc_pydantic_field_show_constraints}} # noqa: F821 autodoc_pydantic_model_member_order = "{{autodoc_pydantic_model_member_order}}" # noqa: F821 +autodoc_pydantic_model_show_config_summary = {{autodoc_pydantic_model_show_config_summary}} # noqa: F821 +autodoc_pydantic_model_show_field_summary = {{autodoc_pydantic_model_show_field_summary}} # noqa: F821 autodoc_pydantic_model_show_json = {{autodoc_pydantic_model_show_json}} # noqa: F821 +autodoc_pydantic_model_show_validator_summary = {{autodoc_pydantic_model_show_validator_summary}} # noqa: F821 +autodoc_pydantic_model_show_validator_members = {{autodoc_pydantic_model_show_validator_members}} # noqa: F821 autodoc_pydantic_settings_show_json = {{autodoc_pydantic_settings_show_json}} # noqa: F821 +# standard table of contents configuration toctree_base = """{toctree} --- caption: "" maxdepth: 2 hidden: true ---""" + toctree_root = f"""```{toctree_base} + {pages} ``` """ +###################### +# INTERNAL FUNCTIONS # +###################### def run_copyreadme(_): out = Path("{{source_dir}}") / "index.md" readme = Path(root) if (root != "" and root != "None") else Path("{{source_dir}}") / "README.md" @@ -201,4 +259,3 @@ def setup(app): app.connect("builder-inited", run_copyreadme) app.connect("builder-inited", run_copycname) app.connect("source-read", run_convert_github_admonitions_to_rst) - {# app.connect("doctree-read", run_add_version_links_to_toctree, priority=500) #}