Skip to content

Clean up and formalize more options #75

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
timkpaine merged 1 commit into from
Feb 3, 2026
Merged

Clean up and formalize more options #75

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 24 additions & 6 deletions yardang/build.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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 = {}
Expand Down Expand Up @@ -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():
Expand All @@ -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,
Expand All @@ -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():
Expand Down
81 changes: 69 additions & 12 deletions yardang/conf.py.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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}}"
Expand All @@ -12,8 +31,6 @@ copyright = """{{copyright}}"""
title = """{{title}}"""
version = "{{version}}"
release = "{{version}}"
html_title = """{{title}} <code style="""
release = "{{version}}"
html_title = """{{title}} <code style='font-size: var(--font-size--small--4);color: var(--sd-color-primary);'>v{{version}}</code>"""
docs_host_root = "{{docs_root}}"
root = "{{root}}"
Expand All @@ -25,9 +42,20 @@ pages = """
"""
use_autoapi = {{use_autoapi}} # noqa: F821

######################
# Standardized below #
######################
#############################################################################################################
# _____ _ _ _ __ _ _ #
# | __ \ | | | (_)/ _| | | | | #
# | | | | ___ _ __ ___ | |_ _ __ ___ ___ __| |_| |_ _ _ | |__ ___| | _____ __ #
# | | | |/ _ \ | '_ \ / _ \| __| | '_ ` _ \ / _ \ / _` | | _| | | | | '_ \ / _ \ |/ _ \ \ /\ / / #
# | |__| | (_) | | | | | (_) | |_ | | | | | | (_) | (_| | | | | |_| | | |_) | __/ | (_) \ V V / #
# |_____/ \___/ |_| |_|\___/ \__| |_| |_| |_|\___/ \__,_|_|_| \__, | |_.__/ \___|_|\___/ \_/\_/ #
# __/ | #
# |___/ #
#############################################################################################################

###################
# BASE EXTENSIONS #
###################
extensions = [
"myst_nb",
"sphinx.ext.napoleon",
Expand All @@ -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}}
Expand All @@ -67,6 +101,10 @@ html_js_files = [
*{{html_js_files}}
]

####################
# SPHINX INTERNALS #
####################

master_doc = "index"
templates_path = ["_templates"]
source_suffix = [".rst", ".md", *{{source_suffix}}]
Expand All @@ -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"
Expand Down Expand Up @@ -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) #}