From 9b7049b21aa6854e826815a7cf9427bc36414c36 Mon Sep 17 00:00:00 2001 From: Sam Wu <22262939+samjwu@users.noreply.github.com> Date: Thu, 19 Sep 2024 17:00:16 -0600 Subject: [PATCH 01/18] refactor(core.py): Set default article info os using all_article_info_os if not present --- src/rocm_docs/core.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/rocm_docs/core.py b/src/rocm_docs/core.py index 85a281e4..2fc0f484 100644 --- a/src/rocm_docs/core.py +++ b/src/rocm_docs/core.py @@ -155,8 +155,7 @@ def _set_page_article_info( continue article_os_info = "" - if "os" not in page: - page["os"] = app.config.all_article_info_os + page.setdefault("os", app.config.all_article_info_os) if "linux" in page["os"]: article_os_info += "Linux" if "windows" in page["os"]: From 6df15ffce827fde4f894ab6d51c7226cbbc46bf4 Mon Sep 17 00:00:00 2001 From: Sam Wu <22262939+samjwu@users.noreply.github.com> Date: Thu, 19 Sep 2024 17:02:20 -0600 Subject: [PATCH 02/18] refactor(core.py): Join article os info from list --- src/rocm_docs/core.py | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/src/rocm_docs/core.py b/src/rocm_docs/core.py index 2fc0f484..906724e2 100644 --- a/src/rocm_docs/core.py +++ b/src/rocm_docs/core.py @@ -154,14 +154,13 @@ def _set_page_article_info( if not path_html.is_file(): continue - article_os_info = "" + os_list = [] page.setdefault("os", app.config.all_article_info_os) if "linux" in page["os"]: - article_os_info += "Linux" + os_list.append("Linux") if "windows" in page["os"]: - if len(article_os_info) > 0: - article_os_info += " and " - article_os_info += "Windows" + os_list.append("Windows") + article_os_info = " and ".join(os_list) modified_info = article_info.replace("", article_os_info) author = app.config.all_article_info_author From 0ea6863c3c2d9a11043543fb341cba398edccca0 Mon Sep 17 00:00:00 2001 From: Sam Wu <22262939+samjwu@users.noreply.github.com> Date: Thu, 19 Sep 2024 17:05:01 -0600 Subject: [PATCH 03/18] fix(article-info.html): Only add apply to string if os list is not empty --- src/rocm_docs/core.py | 2 ++ src/rocm_docs/rocm_docs_theme/components/article-info.html | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/src/rocm_docs/core.py b/src/rocm_docs/core.py index 906724e2..e537dbf5 100644 --- a/src/rocm_docs/core.py +++ b/src/rocm_docs/core.py @@ -161,6 +161,8 @@ def _set_page_article_info( if "windows" in page["os"]: os_list.append("Windows") article_os_info = " and ".join(os_list) + if os_list: + article_os_info = f"Applies to {article_os_info}" modified_info = article_info.replace("", article_os_info) author = app.config.all_article_info_author diff --git a/src/rocm_docs/rocm_docs_theme/components/article-info.html b/src/rocm_docs/rocm_docs_theme/components/article-info.html index 86da0747..f0e4912e 100644 --- a/src/rocm_docs/rocm_docs_theme/components/article-info.html +++ b/src/rocm_docs/rocm_docs_theme/components/article-info.html @@ -1,7 +1,7 @@
- Applies to +
From 08810354fbc2e45789c12c4c2f8b3a496b5f94b7 Mon Sep 17 00:00:00 2001 From: Sam Wu <22262939+samjwu@users.noreply.github.com> Date: Thu, 19 Sep 2024 17:23:29 -0600 Subject: [PATCH 04/18] fix(core.py): Apply os list for article info fix for all article info option --- src/rocm_docs/core.py | 11 ++++++----- .../rocm_docs_theme/components/article-info.html | 4 +--- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/src/rocm_docs/core.py b/src/rocm_docs/core.py index e537dbf5..225799f7 100644 --- a/src/rocm_docs/core.py +++ b/src/rocm_docs/core.py @@ -213,13 +213,14 @@ def _set_all_article_info( if not page.is_file(): continue - article_os_info = "" + os_list = [] if "linux" in app.config.all_article_info_os: - article_os_info += "Linux" + os_list.append("Linux") if "windows" in app.config.all_article_info_os: - if len(article_os_info) > 0: - article_os_info += " and " - article_os_info += "Windows" + os_list.append("Windows") + article_os_info = " and ".join(os_list) + if os_list: + article_os_info = f"Applies to {article_os_info}" date_info = _get_time_last_modified(repo, Path(app.srcdir, page_rel)) if not date_info: diff --git a/src/rocm_docs/rocm_docs_theme/components/article-info.html b/src/rocm_docs/rocm_docs_theme/components/article-info.html index f0e4912e..3a976873 100644 --- a/src/rocm_docs/rocm_docs_theme/components/article-info.html +++ b/src/rocm_docs/rocm_docs_theme/components/article-info.html @@ -1,8 +1,6 @@
-
- -
+
From 57eac49e49b59e8679498dfe747d05a675f39a2f Mon Sep 17 00:00:00 2001 From: Sam Wu <22262939+samjwu@users.noreply.github.com> Date: Thu, 19 Sep 2024 17:32:14 -0600 Subject: [PATCH 05/18] style(article-info.html): Reorder article info --- .../components/article-info.html | 41 ++++++++++--------- 1 file changed, 22 insertions(+), 19 deletions(-) diff --git a/src/rocm_docs/rocm_docs_theme/components/article-info.html b/src/rocm_docs/rocm_docs_theme/components/article-info.html index 3a976873..d87dfd88 100644 --- a/src/rocm_docs/rocm_docs_theme/components/article-info.html +++ b/src/rocm_docs/rocm_docs_theme/components/article-info.html @@ -1,20 +1,23 @@
-
-
-
-
-
-
-

AMD

-
-
-

2023

-
-
-

5 min read

-
-
-
-
-
-
+
+
+
+
+
+

2023

+
+
+

5 min read

+
+
+ +
+
+

AMD

+
+
+
+
+
+
+ \ No newline at end of file From 0cfd347646c6b943f719ccfbc2a15316dc466410 Mon Sep 17 00:00:00 2001 From: Sam Wu <22262939+samjwu@users.noreply.github.com> Date: Fri, 27 Sep 2024 16:46:51 -0600 Subject: [PATCH 06/18] docs(conf.py): Remove OS for all article info --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 3436b84c..559b3f6a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -16,7 +16,7 @@ setting_all_article_info = True -all_article_info_os = ["linux", "windows"] +all_article_info_os = [] # specific settings override any general settings (eg: all_article_info_) article_pages = [ From d5f862b717403525a93907508d631840805fbb81 Mon Sep 17 00:00:00 2001 From: Sam Wu <22262939+samjwu@users.noreply.github.com> Date: Fri, 27 Sep 2024 17:04:40 -0600 Subject: [PATCH 07/18] docs(conf.py): Set empty article info for doxygen integration page --- docs/conf.py | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 559b3f6a..6d4205b5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -15,9 +15,8 @@ external_projects_current_project = "rocm-docs-core" setting_all_article_info = True - all_article_info_os = [] - +all_article_info_author = "" # specific settings override any general settings (eg: all_article_info_) article_pages = [ { @@ -27,7 +26,16 @@ "date": "2024-07-03", "read-time": "2 min read", }, - {"file": "developer_guide/commitizen"}, + { + "file": "user_guide/doxygen_integration", + "os": [], + "author": "", + "date": "", + "read-time": "", + }, + { + "file": "developer_guide/commitizen", + }, ] html_theme = "rocm_docs_theme" From e55ddd85274cbb816c002462ee330d975738b2da Mon Sep 17 00:00:00 2001 From: Sam Wu <22262939+samjwu@users.noreply.github.com> Date: Fri, 27 Sep 2024 17:17:20 -0600 Subject: [PATCH 08/18] refactor(core.py): Set default OS and date to empty --- src/rocm_docs/core.py | 4 ++-- .../components/article-info.html | 18 ++++++++++++++++-- 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/src/rocm_docs/core.py b/src/rocm_docs/core.py index 225799f7..5aa4cc11 100644 --- a/src/rocm_docs/core.py +++ b/src/rocm_docs/core.py @@ -319,7 +319,7 @@ def setup(app: Sphinx) -> dict[str, Any]: ) app.add_config_value( "all_article_info_os", - default=["linux", "windows"], + default=[], rebuild="html", types=str, ) @@ -327,7 +327,7 @@ def setup(app: Sphinx) -> dict[str, Any]: "all_article_info_author", default="", rebuild="html", types=str ) app.add_config_value( - "all_article_info_date", default="2023", rebuild="html", types=str + "all_article_info_date", default="", rebuild="html", types=str ) app.add_config_value( "all_article_info_read_time", default="", rebuild="html", types=str diff --git a/src/rocm_docs/rocm_docs_theme/components/article-info.html b/src/rocm_docs/rocm_docs_theme/components/article-info.html index d87dfd88..3a70ba22 100644 --- a/src/rocm_docs/rocm_docs_theme/components/article-info.html +++ b/src/rocm_docs/rocm_docs_theme/components/article-info.html @@ -4,10 +4,24 @@
-

2023

+

+ + + + 2023 +

-

5 min read

+

+ + + + 5 min read +

From e3c39c10ee109cf68d0ad1e3a9be9014efb9ddd4 Mon Sep 17 00:00:00 2001 From: Sam Wu <22262939+samjwu@users.noreply.github.com> Date: Fri, 27 Sep 2024 17:25:19 -0600 Subject: [PATCH 09/18] refactor: Modify markers in article-info.html --- src/rocm_docs/core.py | 8 ++++---- .../rocm_docs_theme/components/article-info.html | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/rocm_docs/core.py b/src/rocm_docs/core.py index 5aa4cc11..37f01c34 100644 --- a/src/rocm_docs/core.py +++ b/src/rocm_docs/core.py @@ -179,13 +179,13 @@ def _set_page_article_info( if not date_info: date_info = cast(str, app.config.all_article_info_date) - modified_info = modified_info.replace("2023", date_info) + modified_info = modified_info.replace("", date_info) if "read-time" in page: read_time = page["read-time"] else: read_time = _estimate_read_time(path_html) - modified_info = modified_info.replace("5 min read", read_time) + modified_info = modified_info.replace("", read_time) specific_pages.append(page["file"]) _write_article_info(path_html, modified_info) @@ -230,9 +230,9 @@ def _set_all_article_info( modified_info = modified_info.replace( "AMD", app.config.all_article_info_author ) - modified_info = modified_info.replace("2023", date_info) + modified_info = modified_info.replace("", date_info) modified_info = modified_info.replace( - "5 min read", _estimate_read_time(page) + "", _estimate_read_time(page) ) _write_article_info(page, modified_info) diff --git a/src/rocm_docs/rocm_docs_theme/components/article-info.html b/src/rocm_docs/rocm_docs_theme/components/article-info.html index 3a70ba22..42b289e8 100644 --- a/src/rocm_docs/rocm_docs_theme/components/article-info.html +++ b/src/rocm_docs/rocm_docs_theme/components/article-info.html @@ -10,7 +10,7 @@ - 2023 +

@@ -20,7 +20,7 @@ - 5 min read +

From 9699560118083b8478c04eee90059cb885c3b225 Mon Sep 17 00:00:00 2001 From: Sam Wu <22262939+samjwu@users.noreply.github.com> Date: Fri, 27 Sep 2024 17:30:11 -0600 Subject: [PATCH 10/18] style: Add newline to end of file --- src/rocm_docs/rocm_docs_theme/components/article-info.html | 1 - 1 file changed, 1 deletion(-) diff --git a/src/rocm_docs/rocm_docs_theme/components/article-info.html b/src/rocm_docs/rocm_docs_theme/components/article-info.html index 42b289e8..b84a397b 100644 --- a/src/rocm_docs/rocm_docs_theme/components/article-info.html +++ b/src/rocm_docs/rocm_docs_theme/components/article-info.html @@ -34,4 +34,3 @@
- \ No newline at end of file From 9503bbefdad88e132a95df71797798a03ac3eb83 Mon Sep 17 00:00:00 2001 From: Sam Wu <22262939+samjwu@users.noreply.github.com> Date: Fri, 27 Sep 2024 17:32:35 -0600 Subject: [PATCH 11/18] refactor: Remove default author --- src/rocm_docs/core.py | 4 ++-- src/rocm_docs/rocm_docs_theme/components/article-info.html | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/rocm_docs/core.py b/src/rocm_docs/core.py index 37f01c34..a8d50b05 100644 --- a/src/rocm_docs/core.py +++ b/src/rocm_docs/core.py @@ -168,7 +168,7 @@ def _set_page_article_info( author = app.config.all_article_info_author if "author" in page: author = page["author"] - modified_info = modified_info.replace("AMD", author) + modified_info = modified_info.replace("", author) date_info: str | None = None if "date" in page: @@ -228,7 +228,7 @@ def _set_all_article_info( modified_info = article_info.replace("", article_os_info) modified_info = modified_info.replace( - "AMD", app.config.all_article_info_author + "", app.config.all_article_info_author ) modified_info = modified_info.replace("", date_info) modified_info = modified_info.replace( diff --git a/src/rocm_docs/rocm_docs_theme/components/article-info.html b/src/rocm_docs/rocm_docs_theme/components/article-info.html index b84a397b..2f717d3f 100644 --- a/src/rocm_docs/rocm_docs_theme/components/article-info.html +++ b/src/rocm_docs/rocm_docs_theme/components/article-info.html @@ -27,7 +27,7 @@
-

AMD

+

From 50725f60c5dbf6b1980b2a22c5603f24a9227428 Mon Sep 17 00:00:00 2001 From: Sam Wu <22262939+samjwu@users.noreply.github.com> Date: Fri, 27 Sep 2024 17:40:48 -0600 Subject: [PATCH 12/18] refactor(core.py): Split out article info logic into article_info.py --- src/rocm_docs/article_info.py | 194 ++++++++++++++++++++++++++++++++++ src/rocm_docs/core.py | 194 +--------------------------------- 2 files changed, 198 insertions(+), 190 deletions(-) create mode 100644 src/rocm_docs/article_info.py diff --git a/src/rocm_docs/article_info.py b/src/rocm_docs/article_info.py new file mode 100644 index 00000000..5c07b487 --- /dev/null +++ b/src/rocm_docs/article_info.py @@ -0,0 +1,194 @@ +from typing import Any, cast + +import importlib.resources +import os +from pathlib import Path + +import bs4 +import git.repo +from sphinx.application import Sphinx +from sphinx.config import Config + + +def set_article_info(app: Sphinx, _: Config) -> None: + """Add article info headers to HTML pages.""" + if ( + app.config.setting_all_article_info is False + and len(app.config.article_pages) == 0 + ): + return + + article_info = ( + importlib.resources.files("rocm_docs") + .joinpath("rocm_docs_theme/components/article-info.html") + .read_text(encoding="utf-8") + ) + + specific_pages: list[str] = [] + + _set_page_article_info(app, article_info, specific_pages) + + if app.config.setting_all_article_info is True: + _set_all_article_info(app, article_info, specific_pages) + + +def _set_page_article_info( + app: Sphinx, article_info: str, specific_pages: list[str] +) -> None: + """Add article info headers to the configured HTML pages. + + The pages can be set in "article_pages" of the Sphinx configuration. + """ + repo = git.repo.Repo(app.srcdir, search_parent_directories=True) + for page in app.config.article_pages: + path_rel = app.project.doc2path(page["file"], False) + path_html = Path(app.outdir, path_rel).with_suffix(".html") + path_source = Path(app.srcdir, path_rel) + + # FIXME: This will silently skip all files when not building the default + # `html` format (e.g `htmlzip`, `epub` or `pdf`) + if not path_html.is_file(): + continue + + os_list = [] + page.setdefault("os", app.config.all_article_info_os) + if "linux" in page["os"]: + os_list.append("Linux") + if "windows" in page["os"]: + os_list.append("Windows") + article_os_info = " and ".join(os_list) + if os_list: + article_os_info = f"Applies to {article_os_info}" + modified_info = article_info.replace("", article_os_info) + + author = app.config.all_article_info_author + if "author" in page: + author = page["author"] + modified_info = modified_info.replace("", author) + + date_info: str | None = None + if "date" in page: + date_info = page["date"] + else: + date_info = _get_time_last_modified(repo, path_source) + + if not date_info: + date_info = cast(str, app.config.all_article_info_date) + + modified_info = modified_info.replace("", date_info) + + if "read-time" in page: + read_time = page["read-time"] + else: + read_time = _estimate_read_time(path_html) + modified_info = modified_info.replace("", read_time) + + specific_pages.append(page["file"]) + _write_article_info(path_html, modified_info) + + +def _set_all_article_info( + app: Sphinx, article_info: str, specific_pages: list[str] +) -> None: + """Add article info headers with general settings to all HTML pages. + + Pages that have specific settings (configured by "article_pages") are + skipped. + """ + repo = git.repo.Repo(app.srcdir, search_parent_directories=True) + for docname in app.project.docnames: + # skip pages with specific settings + if docname in specific_pages: + continue + + page_rel = app.project.doc2path(docname, False) + page = Path(app.outdir, page_rel).with_suffix(".html") + + # FIXME: This will silently skip all files when not building the default + # `html` format (e.g `htmlzip`, `epub` or `pdf`) + if not page.is_file(): + continue + + os_list = [] + if "linux" in app.config.all_article_info_os: + os_list.append("Linux") + if "windows" in app.config.all_article_info_os: + os_list.append("Windows") + article_os_info = " and ".join(os_list) + if os_list: + article_os_info = f"Applies to {article_os_info}" + + date_info = _get_time_last_modified(repo, Path(app.srcdir, page_rel)) + if not date_info: + date_info = cast(str, app.config.all_article_info_date) + + modified_info = article_info.replace("", article_os_info) + modified_info = modified_info.replace( + "", app.config.all_article_info_author + ) + modified_info = modified_info.replace("", date_info) + modified_info = modified_info.replace( + "", _estimate_read_time(page) + ) + + _write_article_info(page, modified_info) + + +def _get_time_last_modified(repo: git.repo.Repo, path: Path) -> str | None: + try: + time = next( + repo.iter_commits(paths=path, max_count=1) + ).committed_datetime + return time.strftime("%Y-%m-%d") + except StopIteration: + return None + + +def _estimate_read_time(file_name: Path) -> str: + def is_visible(element): + if element.parent.name in [ + "style", + "script", + "[document]", + "head", + "title", + ]: + return False + if isinstance(element, bs4.element.Comment): + return False + return element.string != "\n" + + words_per_minute = 200 + average_word_length = 5 + + with open(file_name, encoding="utf-8") as file: + html = file.read() + soup = bs4.BeautifulSoup(html, "html.parser") + page_text = soup.findAll(text=True) + visible_page_text = filter(is_visible, page_text) + average_word_count = ( + sum(len(line) for line in visible_page_text) / average_word_length + ) + time_minutes = int(max(1, round(average_word_count / words_per_minute))) + return f"{time_minutes} min read time" + + +def _write_article_info(path: os.PathLike[Any], article_info: str) -> None: + with open(path, "r+", encoding="utf8") as file: + page_html = file.read() + soup = bs4.BeautifulSoup(page_html, "html.parser") + + has_article_info = soup.find("div", id="rocm-docs-core-article-info") + if ( + has_article_info is not None + or soup.article is None + or soup.article.h1 is None + ): + return + + soup.article.h1.insert_after( + bs4.BeautifulSoup(article_info, "html.parser") + ) + file.seek(0) + file.truncate(0) + file.write(str(soup)) diff --git a/src/rocm_docs/core.py b/src/rocm_docs/core.py index a8d50b05..233cb2e7 100644 --- a/src/rocm_docs/core.py +++ b/src/rocm_docs/core.py @@ -7,23 +7,21 @@ from __future__ import annotations -from typing import Any, Generic, TypeVar, cast +from typing import Any, Generic, TypeVar -import importlib.resources import inspect import os import urllib.parse from abc import ABC, abstractmethod -from pathlib import Path -import bs4 -import git.repo from pydata_sphinx_theme.utils import ( # type: ignore[import-untyped] config_provided_by_user, ) from sphinx.application import Sphinx from sphinx.config import Config +from rocm_docs import article_info + T = TypeVar("T") @@ -114,190 +112,6 @@ def _force_notfound_prefix(app: Sphinx, _: Config) -> None: app.config.notfound_urls_prefix = components.path -def _set_article_info(app: Sphinx, _: Config) -> None: - """Add article info headers to HTML pages.""" - if ( - app.config.setting_all_article_info is False - and len(app.config.article_pages) == 0 - ): - return - - article_info = ( - importlib.resources.files("rocm_docs") - .joinpath("rocm_docs_theme/components/article-info.html") - .read_text(encoding="utf-8") - ) - - specific_pages: list[str] = [] - - _set_page_article_info(app, article_info, specific_pages) - - if app.config.setting_all_article_info is True: - _set_all_article_info(app, article_info, specific_pages) - - -def _set_page_article_info( - app: Sphinx, article_info: str, specific_pages: list[str] -) -> None: - """Add article info headers to the configured HTML pages. - - The pages can be set in "article_pages" of the Sphinx configuration. - """ - repo = git.repo.Repo(app.srcdir, search_parent_directories=True) - for page in app.config.article_pages: - path_rel = app.project.doc2path(page["file"], False) - path_html = Path(app.outdir, path_rel).with_suffix(".html") - path_source = Path(app.srcdir, path_rel) - - # FIXME: This will silently skip all files when not building the default - # `html` format (e.g `htmlzip`, `epub` or `pdf`) - if not path_html.is_file(): - continue - - os_list = [] - page.setdefault("os", app.config.all_article_info_os) - if "linux" in page["os"]: - os_list.append("Linux") - if "windows" in page["os"]: - os_list.append("Windows") - article_os_info = " and ".join(os_list) - if os_list: - article_os_info = f"Applies to {article_os_info}" - modified_info = article_info.replace("", article_os_info) - - author = app.config.all_article_info_author - if "author" in page: - author = page["author"] - modified_info = modified_info.replace("", author) - - date_info: str | None = None - if "date" in page: - date_info = page["date"] - else: - date_info = _get_time_last_modified(repo, path_source) - - if not date_info: - date_info = cast(str, app.config.all_article_info_date) - - modified_info = modified_info.replace("", date_info) - - if "read-time" in page: - read_time = page["read-time"] - else: - read_time = _estimate_read_time(path_html) - modified_info = modified_info.replace("", read_time) - - specific_pages.append(page["file"]) - _write_article_info(path_html, modified_info) - - -def _set_all_article_info( - app: Sphinx, article_info: str, specific_pages: list[str] -) -> None: - """Add article info headers with general settings to all HTML pages. - - Pages that have specific settings (configured by "article_pages") are - skipped. - """ - repo = git.repo.Repo(app.srcdir, search_parent_directories=True) - for docname in app.project.docnames: - # skip pages with specific settings - if docname in specific_pages: - continue - - page_rel = app.project.doc2path(docname, False) - page = Path(app.outdir, page_rel).with_suffix(".html") - - # FIXME: This will silently skip all files when not building the default - # `html` format (e.g `htmlzip`, `epub` or `pdf`) - if not page.is_file(): - continue - - os_list = [] - if "linux" in app.config.all_article_info_os: - os_list.append("Linux") - if "windows" in app.config.all_article_info_os: - os_list.append("Windows") - article_os_info = " and ".join(os_list) - if os_list: - article_os_info = f"Applies to {article_os_info}" - - date_info = _get_time_last_modified(repo, Path(app.srcdir, page_rel)) - if not date_info: - date_info = cast(str, app.config.all_article_info_date) - - modified_info = article_info.replace("", article_os_info) - modified_info = modified_info.replace( - "", app.config.all_article_info_author - ) - modified_info = modified_info.replace("", date_info) - modified_info = modified_info.replace( - "", _estimate_read_time(page) - ) - - _write_article_info(page, modified_info) - - -def _get_time_last_modified(repo: git.repo.Repo, path: Path) -> str | None: - try: - time = next( - repo.iter_commits(paths=path, max_count=1) - ).committed_datetime - return time.strftime("%Y-%m-%d") - except StopIteration: - return None - - -def _estimate_read_time(file_name: Path) -> str: - def is_visible(element): - if element.parent.name in [ - "style", - "script", - "[document]", - "head", - "title", - ]: - return False - if isinstance(element, bs4.element.Comment): - return False - return element.string != "\n" - - words_per_minute = 200 - average_word_length = 5 - - with open(file_name, encoding="utf-8") as file: - html = file.read() - soup = bs4.BeautifulSoup(html, "html.parser") - page_text = soup.findAll(text=True) - visible_page_text = filter(is_visible, page_text) - average_word_count = ( - sum(len(line) for line in visible_page_text) / average_word_length - ) - time_minutes = int(max(1, round(average_word_count / words_per_minute))) - return f"{time_minutes} min read time" - - -def _write_article_info(path: os.PathLike[Any], article_info: str) -> None: - with open(path, "r+", encoding="utf8") as file: - page_html = file.read() - soup = bs4.BeautifulSoup(page_html, "html.parser") - - has_article_info = soup.find("div", id="rocm-docs-core-article-info") - if ( - has_article_info is not None - or soup.article is None - or soup.article.h1 is None - ): - return - - soup.article.h1.insert_after( - bs4.BeautifulSoup(article_info, "html.parser") - ) - file.seek(0) - file.truncate(0) - file.write(str(soup)) - - def setup(app: Sphinx) -> dict[str, Any]: """Set up rocm_docs.core as a Sphinx extension.""" required_extensions = [ @@ -339,5 +153,5 @@ def setup(app: Sphinx) -> dict[str, Any]: # Run before notfound.extension sees the config (default priority(=500)) app.connect("config-inited", _force_notfound_prefix, priority=400) app.connect("config-inited", _DefaultSettings.update_config) - app.connect("build-finished", _set_article_info, priority=1000) + app.connect("build-finished", article_info.set_article_info, priority=1000) return {"parallel_read_safe": True, "parallel_write_safe": True} From 8fd6e52f2cb678bb0eea3f26b4b524fd302b6df5 Mon Sep 17 00:00:00 2001 From: Sam Wu <22262939+samjwu@users.noreply.github.com> Date: Tue, 8 Oct 2024 13:35:05 -0600 Subject: [PATCH 13/18] docs(conf.py): Clear article info on article info page --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 6d4205b5..622a01df 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -27,7 +27,7 @@ "read-time": "2 min read", }, { - "file": "user_guide/doxygen_integration", + "file": "user_guide/article_info", "os": [], "author": "", "date": "", From ca11df6b306f93894e5161dd618f3c86fb64a8f4 Mon Sep 17 00:00:00 2001 From: Sam Wu <22262939+samjwu@users.noreply.github.com> Date: Thu, 24 Oct 2024 17:14:05 -0600 Subject: [PATCH 14/18] refactor(article-info.html): Add custom class to span with svgs in article info --- src/rocm_docs/rocm_docs_theme/components/article-info.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/rocm_docs/rocm_docs_theme/components/article-info.html b/src/rocm_docs/rocm_docs_theme/components/article-info.html index 2f717d3f..15d41247 100644 --- a/src/rocm_docs/rocm_docs_theme/components/article-info.html +++ b/src/rocm_docs/rocm_docs_theme/components/article-info.html @@ -5,7 +5,7 @@

- +

- +