From b0edcc891ee685e884bff8aaeab31314d3ac9d95 Mon Sep 17 00:00:00 2001 From: Yao Xiao <108576690+Charlie-XIAO@users.noreply.github.com> Date: Fri, 23 Feb 2024 10:55:48 +0800 Subject: [PATCH 1/4] [doc build] use jinja2 template for rendering --- .gitignore | 1 + doc/conf.py | 140 +++--------------- doc/index.rst.template | 34 +++++ doc/min_dependency_substitutions.rst.template | 3 + doc/min_dependency_table.rst.template | 13 ++ 5 files changed, 71 insertions(+), 120 deletions(-) create mode 100644 doc/index.rst.template create mode 100644 doc/min_dependency_substitutions.rst.template create mode 100644 doc/min_dependency_table.rst.template diff --git a/.gitignore b/.gitignore index 7b4f61beaf353..73ea0076ceefb 100644 --- a/.gitignore +++ b/.gitignore @@ -20,6 +20,7 @@ doc/css/* !doc/css/.gitkeep doc/modules/generated/ doc/datasets/generated/ +doc/index.rst doc/min_dependency_table.rst doc/min_dependency_substitutions.rst *.pdf diff --git a/doc/conf.py b/doc/conf.py index e94021069a23a..a8ee7e89df67c 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -15,7 +15,6 @@ import sys import warnings from datetime import datetime -from io import StringIO from pathlib import Path from sklearn.externals._packaging.version import parse @@ -27,6 +26,7 @@ # absolute, like shown here. sys.path.insert(0, os.path.abspath("sphinxext")) +import jinja2 import sphinx_gallery from github_link import make_linkcode_resolve from sphinx_gallery.notebook import add_code_cell, add_markdown_cell @@ -739,121 +739,6 @@ def filter_search_index(app, exception): f.write(searchindex_text) -def generate_min_dependency_table(): - """Generate min dependency table for docs.""" - from sklearn._min_dependencies import dependent_packages - - # get length of header - package_header_len = max(len(package) for package in dependent_packages) + 4 - version_header_len = len("Minimum Version") + 4 - tags_header_len = max(len(tags) for _, tags in dependent_packages.values()) + 4 - - output = StringIO() - output.write( - " ".join( - ["=" * package_header_len, "=" * version_header_len, "=" * tags_header_len] - ) - ) - output.write("\n") - dependency_title = "Dependency" - version_title = "Minimum Version" - tags_title = "Purpose" - - output.write( - f"{dependency_title:<{package_header_len}} " - f"{version_title:<{version_header_len}} " - f"{tags_title}\n" - ) - - output.write( - " ".join( - ["=" * package_header_len, "=" * version_header_len, "=" * tags_header_len] - ) - ) - output.write("\n") - - for package, (version, tags) in dependent_packages.items(): - output.write( - f"{package:<{package_header_len}} {version:<{version_header_len}} {tags}\n" - ) - - output.write( - " ".join( - ["=" * package_header_len, "=" * version_header_len, "=" * tags_header_len] - ) - ) - output.write("\n") - output = output.getvalue() - - with (Path(".") / "min_dependency_table.rst").open("w", encoding="utf-8") as f: - f.write(output) - - -def generate_min_dependency_substitutions(): - """Generate min dependency substitutions for docs.""" - from sklearn._min_dependencies import dependent_packages - - output = StringIO() - - for package, (version, _) in dependent_packages.items(): - package = package.capitalize() - output.write(f".. |{package}MinVersion| replace:: {version}") - output.write("\n") - - output = output.getvalue() - - with (Path(".") / "min_dependency_substitutions.rst").open( - "w", encoding="utf-8" - ) as f: - f.write(output) - - -def generate_index_rst(): - """Generate index.rst. - - The reason for generating this file at build time is to allow specifying the - development link as a variable. - https://github.com/scikit-learn/scikit-learn/pull/22550 - """ - development_link = ( - "developers/index" - if parsed_version.is_devrelease - else "https://scikit-learn.org/dev/developers/index.html" - ) - - output = f""" -.. title:: Index - -.. Define the overall structure, that affects the prev-next buttons and the order - of the sections in the top navbar. - -.. toctree:: - :hidden: - :maxdepth: 2 - - Install - user_guide - API - auto_examples/index - Community - getting_started - Tutorials - whats_new - Glossary - Development <{development_link}> - FAQ - support - related_projects - roadmap - Governance - about - Other Versions and Download -""" - - with (Path(".") / "index.rst").open("w", encoding="utf-8") as f: - f.write(output) - - # Config for sphinx_issues # we use the issues path for PRs since the issues URL will forward @@ -1000,7 +885,22 @@ def setup(app): "https://github.com/": {"Authorization": f"token {github_token}"}, } -# Write the pages prior to any sphinx event -generate_index_rst() -generate_min_dependency_table() -generate_min_dependency_substitutions() +# Convert the template rst files into actual rst files prior to any sphinx event + +from sklearn._min_dependencies import dependent_packages + +# (file name without suffix, kwargs for rendering) +rst_templates = [ + ("index", {"is_devrelease": parsed_version.is_devrelease}), + ("min_dependency_table", {"dependent_packages": dependent_packages}), + ("min_dependency_substitutions", {"dependent_packages": dependent_packages}), +] + +for target_name, kwargs in rst_templates: + # Read the corresponding template file into jinja2 + with (Path(".") / f"{target_name}.rst.template").open("r", encoding="utf-8") as f: + t = jinja2.Template(f.read()) + + # Render the template and write to the target + with (Path(".") / f"{target_name}.rst").open("w", encoding="utf-8") as f: + f.write(t.render(**kwargs)) diff --git a/doc/index.rst.template b/doc/index.rst.template new file mode 100644 index 0000000000000..bd0e83ed10b80 --- /dev/null +++ b/doc/index.rst.template @@ -0,0 +1,34 @@ +.. title:: Index + +.. Define the overall structure, that affects the prev-next buttons and the order + of the sections in the top navbar. + +{#- If development build, link to local page; otherwise link to the development -#} +{#- version; see https://github.com/scikit-learn/scikit-learn/pull/22550 -#} +{% if is_devrelease -%} + {%- set development_link = "developers/index" -%} +{%- else -%} + {%- set development_link = "https://scikit-learn.org/dev/developers/index.html" -%} +{%- endif %} + +.. toctree:: + :hidden: + :maxdepth: 2 + + Install + user_guide + API + auto_examples/index + Community + getting_started + Tutorials + whats_new + Glossary + Development <{{ development_link }}> + FAQ + support + related_projects + roadmap + Governance + about + Other Versions and Download diff --git a/doc/min_dependency_substitutions.rst.template b/doc/min_dependency_substitutions.rst.template new file mode 100644 index 0000000000000..946de84902b3b --- /dev/null +++ b/doc/min_dependency_substitutions.rst.template @@ -0,0 +1,3 @@ +{% for package, (version, _) in dependent_packages.items() -%} +.. |{{ package|capitalize }}MinVersion| replace:: {{ version }} +{% endfor %} diff --git a/doc/min_dependency_table.rst.template b/doc/min_dependency_table.rst.template new file mode 100644 index 0000000000000..fbe58633e913a --- /dev/null +++ b/doc/min_dependency_table.rst.template @@ -0,0 +1,13 @@ +.. list-table:: + :header-rows: 1 + + * - Dependency + - Minimum Version + - Purpose + + {% for package, (version, tags) in dependent_packages.items() -%} + * - {{ package }} + - {{ version }} + - {{ tags }} + + {% endfor %} From 9711f5ffde71573dc08ae3d594be370089303d2b Mon Sep 17 00:00:00 2001 From: Yao Xiao <108576690+Charlie-XIAO@users.noreply.github.com> Date: Sat, 24 Feb 2024 10:11:46 +0800 Subject: [PATCH 2/4] [doc build] allow different template name and target file name --- doc/conf.py | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index a8ee7e89df67c..1e218a637bdd3 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -889,18 +889,28 @@ def setup(app): from sklearn._min_dependencies import dependent_packages -# (file name without suffix, kwargs for rendering) +# (template name, file name, kwargs for rendering) rst_templates = [ - ("index", {"is_devrelease": parsed_version.is_devrelease}), - ("min_dependency_table", {"dependent_packages": dependent_packages}), - ("min_dependency_substitutions", {"dependent_packages": dependent_packages}), + ("index", "index", {"is_devrelease": parsed_version.is_devrelease}), + ( + "min_dependency_table", + "min_dependency_table", + {"dependent_packages": dependent_packages}, + ), + ( + "min_dependency_substitutions", + "min_dependency_substitutions", + {"dependent_packages": dependent_packages}, + ), ] -for target_name, kwargs in rst_templates: +for rst_template_name, rst_target_name, kwargs in rst_templates: # Read the corresponding template file into jinja2 - with (Path(".") / f"{target_name}.rst.template").open("r", encoding="utf-8") as f: + with (Path(".") / f"{rst_template_name}.rst.template").open( + "r", encoding="utf-8" + ) as f: t = jinja2.Template(f.read()) # Render the template and write to the target - with (Path(".") / f"{target_name}.rst").open("w", encoding="utf-8") as f: + with (Path(".") / f"{rst_target_name}.rst").open("w", encoding="utf-8") as f: f.write(t.render(**kwargs)) From 25c30756df1a392debbaa52b06d9186a7ba09954 Mon Sep 17 00:00:00 2001 From: Yao Xiao <108576690+Charlie-XIAO@users.noreply.github.com> Date: Sun, 25 Feb 2024 12:00:37 +0800 Subject: [PATCH 3/4] [doc build] trigger full build From 3e4ddbcedf03a4967d6ca5d8a5d4747100703111 Mon Sep 17 00:00:00 2001 From: Yao Xiao <108576690+Charlie-XIAO@users.noreply.github.com> Date: Tue, 27 Feb 2024 10:51:58 +0800 Subject: [PATCH 4/4] simplify logic in jinja2 and some comments --- doc/conf.py | 14 +++++++++++--- doc/index.rst.template | 8 -------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 1e218a637bdd3..dddb0f8f7ad7c 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -885,13 +885,21 @@ def setup(app): "https://github.com/": {"Authorization": f"token {github_token}"}, } -# Convert the template rst files into actual rst files prior to any sphinx event +# -- Convert .rst.template files to .rst --------------------------------------- from sklearn._min_dependencies import dependent_packages -# (template name, file name, kwargs for rendering) +# If development build, link to local page in the top navbar; otherwise link to the +# development version; see https://github.com/scikit-learn/scikit-learn/pull/22550 +if parsed_version.is_devrelease: + development_link = "developers/index" +else: + development_link = "https://scikit-learn.org/dev/developers/index.html" + +# Define the templates and target files for conversion +# Each entry is in the format (template name, file name, kwargs for rendering) rst_templates = [ - ("index", "index", {"is_devrelease": parsed_version.is_devrelease}), + ("index", "index", {"development_link": development_link}), ( "min_dependency_table", "min_dependency_table", diff --git a/doc/index.rst.template b/doc/index.rst.template index bd0e83ed10b80..9a94c533495ee 100644 --- a/doc/index.rst.template +++ b/doc/index.rst.template @@ -3,14 +3,6 @@ .. Define the overall structure, that affects the prev-next buttons and the order of the sections in the top navbar. -{#- If development build, link to local page; otherwise link to the development -#} -{#- version; see https://github.com/scikit-learn/scikit-learn/pull/22550 -#} -{% if is_devrelease -%} - {%- set development_link = "developers/index" -%} -{%- else -%} - {%- set development_link = "https://scikit-learn.org/dev/developers/index.html" -%} -{%- endif %} - .. toctree:: :hidden: :maxdepth: 2