Skip to content

DOC [PST] use jinja2 template for rst generation #28511

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
merged 4 commits into from
Feb 27, 2024
Merged

DOC [PST] use jinja2 template for rst generation #28511

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b0edcc8
[doc build] use jinja2 template for rendering
Charlie-XIAO Feb 23, 2024
9711f5f
[doc build] allow different template name and target file name
Charlie-XIAO Feb 24, 2024
25c3075
[doc build] trigger full build
Charlie-XIAO Feb 25, 2024
3e4ddbc
simplify logic in jinja2 and some comments
Charlie-XIAO Feb 27, 2024
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
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
158 changes: 38 additions & 120 deletions doc/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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 <install>
user_guide
API <modules/classes>
auto_examples/index
Community <https://blog.scikit-learn.org/>
getting_started
Tutorials <tutorial/index>
whats_new
Glossary <glossary>
Development <{development_link}>
FAQ <faq>
support
related_projects
roadmap
Governance <governance>
about
Other Versions and Download <https://scikit-learn.org/dev/versions.html>
"""

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
Expand Down Expand Up @@ -1000,7 +885,40 @@ 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 .rst.template files to .rst ---------------------------------------

from sklearn._min_dependencies import dependent_packages

# 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", {"development_link": development_link}),
(
"min_dependency_table",
"min_dependency_table",
{"dependent_packages": dependent_packages},
),
(
"min_dependency_substitutions",
"min_dependency_substitutions",
{"dependent_packages": dependent_packages},
),
]

for rst_template_name, rst_target_name, kwargs in rst_templates:
# Read the corresponding template file into jinja2
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"{rst_target_name}.rst").open("w", encoding="utf-8") as f:
f.write(t.render(**kwargs))
26 changes: 26 additions & 0 deletions doc/index.rst.template
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
.. 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 <install>
user_guide
API <modules/classes>
auto_examples/index
Community <https://blog.scikit-learn.org/>
getting_started
Tutorials <tutorial/index>
whats_new
Glossary <glossary>
Development <{{ development_link }}>
FAQ <faq>
support
related_projects
roadmap
Governance <governance>
about
Other Versions and Download <https://scikit-learn.org/dev/versions.html>
3 changes: 3 additions & 0 deletions doc/min_dependency_substitutions.rst.template
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{% for package, (version, _) in dependent_packages.items() -%}
.. |{{ package|capitalize }}MinVersion| replace:: {{ version }}
{% endfor %}
13 changes: 13 additions & 0 deletions doc/min_dependency_table.rst.template
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 %}