stouputils 1.18.6__py3-none-any.whl → 1.19.0__py3-none-any.whl

stouputils/applications/automatic_docs.py

@@ -68,8 +68,6 @@ Example of GitHub Actions workflow:
 # Imports
 import os
 import shutil
-import subprocess
-import sys
 from collections.abc import Callable
 from typing import Any
 
@@ -79,7 +77,7 @@ from ..io import clean_path, json_dump, super_open
 from ..print import info
 
 # Constants
-REQUIREMENTS: list[str] = ["m2r2", "myst_parser"]
+REQUIREMENTS: list[str] = ["myst_parser"]
 """ List of requirements for automatic_docs to work. """
 
 # Functions
@@ -185,6 +183,12 @@ copybutton_selector = ":not(.prompt) > div.highlight pre"
 templates_path: list[str] = ["_templates"]
 exclude_patterns: list[str] = []
 
+# Allow both .rst and .md (MyST) sources
+source_suffix = {{
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}}
+
 # HTML output options
 html_theme: str = "{html_theme}"
 html_static_path: list[str] = ["_static"]
@@ -205,7 +209,6 @@ html_theme_options: dict[str, Any] = {{
 		"github_repo": github_repo,
 		"github_version": "main",
 		"conf_py_path": "/docs/source/",
-		"source_suffix": [".rst", ".md"],
 		"default_mode": "dark",
 	}
 
@@ -318,23 +321,7 @@ def get_versions_from_github(github_user: str, github_repo: str, recent_minor_ve
 		version_list = ["latest"]
 	return version_list
 
-def markdown_to_rst(markdown_content: str) -> str:
-	""" Convert markdown content to RST format.
-
-	Args:
-		markdown_content (str): Markdown content
-
-	Returns:
-		str: RST content
-	"""
-	if not markdown_content:
-		return ""
-
-	# Convert markdown to RST and return it
-	import m2r2  # type: ignore
-	return m2r2.convert(markdown_content)	# type: ignore
-
-def generate_index_rst(
+def generate_index_md(
 	readme_path: str,
 	index_path: str,
 	project: str,
@@ -343,11 +330,14 @@ def generate_index_rst(
 	get_versions_function: Callable[[str, str, int], list[str]] = get_versions_from_github,
 	recent_minor_versions: int = 2,
 ) -> None:
-	""" Generate index.rst from README.md content.
+	""" Generate `index.md` (MyST) from README.md content.
+
+	This keeps the README content as Markdown (no conversion) and uses the MyST
+	`toctree` directive to include module docs.
 
 	Args:
 		readme_path            (str): Path to the README.md file
-		index_path             (str): Path where index.rst should be created
+		index_path             (str): Path where index.md should be created
 		project                (str): Name of the project
 		github_user            (str): GitHub username
 		github_repo            (str): GitHub repository name
@@ -358,50 +348,44 @@ def generate_index_rst(
 	with open(readme_path, encoding="utf-8") as f:
 		readme_content: str = f.read()
 
-	# Generate version selector
-	version_selector: str = "\n\n**Versions**: "
-
-	# Get versions from GitHub
+	# Generate version selector (markdown links)
 	version_list: list[str] = get_versions_function(github_user, github_repo, recent_minor_versions)
-
-	# Create version links
 	version_links: list[str] = []
 	for version in version_list:
 		if version == "latest":
-			version_links.append("`latest <../latest/>`_")
+			version_links.append("[latest](../latest/)")
 		else:
-			version_links.append(f"`v{version} <../v{version}/>`_")
-	version_selector += ", ".join(version_links)
+			version_links.append(f"[v{version}](../v{version}/)")
+	version_selector: str = "\n\n**Versions**: " + ", ".join(version_links)
 
-	# Generate module documentation section
+	# Module documentation toctree (MyST)
 	project_module: str = project.lower()
 	module_docs: str = f"""
-.. toctree::
-   :maxdepth: 10
+```{{toctree}}
+:maxdepth: 10
 
-   modules/{project_module}
+modules/{project_module}
+```
 """
-	module_docs = markdown_to_rst(f"""
-Here is the complete unsorted documentation for all modules in the {project} project.<br>
-Prefer to use the search button at the top to find what you need!
-""") + module_docs
-
-	# Convert markdown to RST
-	rst_content: str = f"""
-✨ Welcome to {project.capitalize()} Documentation ✨
-{'=' * 100}
+
+	# Build final markdown content
+	md_content: str = f"""
+# ✨ Welcome to {project.capitalize()} Documentation ✨
+
 {version_selector}
 
-{markdown_to_rst(readme_content)}
+{readme_content}
+
+---
+
+## Module Documentation
 
-📖 Module Documentation
-{'-' * 100}
 {module_docs}
 """
 
-	# Write the RST file
+	# Write the Markdown file
 	with open(index_path, "w", encoding="utf-8") as f:
-		f.write(rst_content)
+		f.write(md_content)
 
 def generate_documentation(
 	source_dir: str,
@@ -418,9 +402,8 @@ def generate_documentation(
 		build_dir         (str): Build directory
 	"""
 	# Generate module documentation using sphinx-apidoc
-	subprocess.run([
-		sys.executable,
-		"-m", "sphinx.ext.apidoc",
+	from sphinx.ext.apidoc import main as sphinx_apidoc_main
+	sphinx_apidoc_main([
 		"-o", modules_dir,
 		"-f", "-e", "-M",
 		"--no-toc",
@@ -428,17 +411,16 @@ def generate_documentation(
 		"--implicit-namespaces",
 		"--module-first",
 		project_dir,
-	], check=True)
+	])
 
 	# Build HTML documentation
-	subprocess.run([
-		sys.executable,
-		"-m", "sphinx",
+	from sphinx.cmd.build import main as sphinx_build_main
+	sphinx_build_main([
 		"-b", "html",
 		"-a",
 		source_dir,
 		build_dir,
-	], check=True)
+	])
 
 def generate_redirect_html(filepath: str) -> None:
 	""" Generate HTML content for redirect page.
@@ -478,7 +460,7 @@ def update_documentation(
 	recent_minor_versions: int = 2,
 
 	get_versions_function: Callable[[str, str, int], list[str]] = get_versions_from_github,
-	generate_index_function: Callable[..., None] = generate_index_rst,
+	generate_index_function: Callable[..., None] = generate_index_md,
 	generate_docs_function: Callable[..., None] = generate_documentation,
 	generate_redirect_function: Callable[[str], None] = generate_redirect_html,
 	get_conf_content_function: Callable[..., str] = get_sphinx_conf_content
@@ -501,7 +483,7 @@ def update_documentation(
 		recent_minor_versions      (int): Number of recent minor versions to show all patches for. Defaults to 2
 
 		get_versions_function      (Callable[[str, str, int], list[str]]): Function to get versions from GitHub
-		generate_index_function    (Callable[..., None]): Function to generate index.rst
+		generate_index_function    (Callable[..., None]): Function to generate index.md
 		generate_docs_function     (Callable[..., None]): Function to generate documentation
 		generate_redirect_function (Callable[[str], None]): Function to create redirect file
 		get_conf_content_function  (Callable[..., str]): Function to get Sphinx conf.py content
@@ -573,9 +555,9 @@ a:hover {
 }
 """)
 
-	# Generate index.rst from README.md
+	# Generate index.md from README.md (use MyST instead of converting to RST)
 	readme_path: str = f"{root_path}/README.md"
-	index_path: str = f"{source_dir}/index.rst"
+	index_path: str = f"{source_dir}/index.md"
 	generate_index_function(
 		readme_path=readme_path,
 		index_path=index_path,

stouputils/applications/automatic_docs.pyi

@@ -44,21 +44,15 @@ def get_versions_from_github(github_user: str, github_repo: str, recent_minor_ve
 \tReturns:
 \t\tlist[str]: List of versions, with 'latest' as first element
 \t"""
-def markdown_to_rst(markdown_content: str) -> str:
-    """ Convert markdown content to RST format.
+def generate_index_md(readme_path: str, index_path: str, project: str, github_user: str, github_repo: str, get_versions_function: Callable[[str, str, int], list[str]] = ..., recent_minor_versions: int = 2) -> None:
+    """ Generate `index.md` (MyST) from README.md content.
 
-\tArgs:
-\t\tmarkdown_content (str): Markdown content
-
-\tReturns:
-\t\tstr: RST content
-\t"""
-def generate_index_rst(readme_path: str, index_path: str, project: str, github_user: str, github_repo: str, get_versions_function: Callable[[str, str, int], list[str]] = ..., recent_minor_versions: int = 2) -> None:
-    """ Generate index.rst from README.md content.
+\tThis keeps the README content as Markdown (no conversion) and uses the MyST
+\t`toctree` directive to include module docs.
 
 \tArgs:
 \t\treadme_path            (str): Path to the README.md file
-\t\tindex_path             (str): Path where index.rst should be created
+\t\tindex_path             (str): Path where index.md should be created
 \t\tproject                (str): Name of the project
 \t\tgithub_user            (str): GitHub username
 \t\tgithub_repo            (str): GitHub repository name
@@ -99,7 +93,7 @@ def update_documentation(root_path: str, project: str, project_dir: str = '', au
 \t\trecent_minor_versions      (int): Number of recent minor versions to show all patches for. Defaults to 2
 
 \t\tget_versions_function      (Callable[[str, str, int], list[str]]): Function to get versions from GitHub
-\t\tgenerate_index_function    (Callable[..., None]): Function to generate index.rst
+\t\tgenerate_index_function    (Callable[..., None]): Function to generate index.md
 \t\tgenerate_docs_function     (Callable[..., None]): Function to generate documentation
 \t\tgenerate_redirect_function (Callable[[str], None]): Function to create redirect file
 \t\tget_conf_content_function  (Callable[..., str]): Function to get Sphinx conf.py content

{stouputils-1.18.6.dist-info → stouputils-1.19.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: stouputils
-Version: 1.18.6
+Version: 1.19.0
 Summary: Stouputils is a collection of utility modules designed to simplify and enhance the development process. It includes a range of tools for tasks such as execution of doctests, display utilities, decorators, as well as context managers, and many more.
 Keywords: utilities,tools,helpers,development,python
 Author: Stoupy51
@@ -26,7 +26,6 @@ Requires-Dist: tensorflow ; extra == 'data-science'
 Requires-Dist: scikit-learn ; extra == 'data-science'
 Requires-Dist: pywavelets ; extra == 'data-science'
 Requires-Dist: mypy ; extra == 'docs'
-Requires-Dist: m2r2 ; extra == 'docs'
 Requires-Dist: myst-parser ; extra == 'docs'
 Requires-Dist: sphinx-copybutton ; extra == 'docs'
 Requires-Dist: sphinx-design ; extra == 'docs'
@@ -54,9 +53,11 @@ Stouputils is a collection of utility modules designed to simplify and enhance t
 It includes a range of tools for tasks such as execution of doctests, display utilities, decorators, as well as context managers.<br>
 Start now by installing the package: `pip install stouputils`.<br>
 
-<a href="https://colab.research.google.com/drive/1mJ-KL-zXzIk1oKDxO6FC1SFfm-BVKG-P?usp=sharing" target="_blank" rel="noopener noreferrer" style="text-decoration: none;"><div class="admonition">
+<a href="https://colab.research.google.com/drive/1mJ-KL-zXzIk1oKDxO6FC1SFfm-BVKG-P?usp=sharing" target="_blank" rel="noopener noreferrer" style="text-decoration: none;">
+<div class="admonition" style="padding-bottom: 1rem;">
 📖 <b>Want to see examples?</b> Check out our <u>Google Colab notebook</u> with practical usage examples!
-</div></a>
+</div>
+</a>
 
 ## 🚀 Project File Tree
 <html>

{stouputils-1.18.6.dist-info → stouputils-1.19.0.dist-info}/RECORD

@@ -7,8 +7,8 @@ stouputils/all_doctests.py,sha256=jQ7HXWoj2VTUbsu8eBq7EiW9mbx-_yXycdpS1fD8Tro,65
 stouputils/all_doctests.pyi,sha256=R3FRKaQv3sTZbxLvvsChHZZKygVMhmL6pqrYYLqvZCg,2017
 stouputils/applications/__init__.py,sha256=dbjwZt8PZF043KoJSItqCpH32FtRxN5sgV-8Q2b1l10,457
 stouputils/applications/__init__.pyi,sha256=DTYq2Uqq1uLzCMkFByjRqdtREA-9SaQnp4QpgmCEPFg,56
-stouputils/applications/automatic_docs.py,sha256=_6XbCuVi2EiSdkiPZ7XHr5mUGh2ZORev8Vd0tJDb0ug,20561
-stouputils/applications/automatic_docs.pyi,sha256=sfFXpVE5y5Z907HEjKzpZ_9zM34d-jKNDQCdMx7E-9s,6189
+stouputils/applications/automatic_docs.py,sha256=piYkrF4_Sg3h9Le3vB7Ni7GmU7zhIDcvhyrm-OGCax8,20123
+stouputils/applications/automatic_docs.pyi,sha256=sBzcz1V98hyGLKRe8h9S6X_uXMQL798yjCTmERNQt14,6121
 stouputils/applications/upscaler/__init__.py,sha256=8vrca93OYu5GQJrZO1GvnAbptzyhu_L0DnP3M9unlA0,1142
 stouputils/applications/upscaler/__init__.pyi,sha256=VSp6Tq09ATCTdfnjhbDnu7lblaLLGbCNi-E22jYxa88,67
 stouputils/applications/upscaler/config.py,sha256=3WHJv6fznM03nWpdvy72OheuJvNgOZfHH4GEjyRpnZU,5559
@@ -156,7 +156,7 @@ stouputils/typing.py,sha256=TwvxrvxhBRkyHkoOpfyXebN13M3xJb8MAjKXiNIWjew,2205
 stouputils/typing.pyi,sha256=U2UmFZausMYpnsUQROQE2JOwHcjx2hKV0rJuOdR57Ew,1341
 stouputils/version_pkg.py,sha256=Jsp-s03L14DkiZ94vQgrlQmaxApfn9DC8M_nzT1SJLk,7014
 stouputils/version_pkg.pyi,sha256=QPvqp1U3QA-9C_CC1dT9Vahv1hXEhstbM7x5uzMZSsQ,755
-stouputils-1.18.6.dist-info/WHEEL,sha256=e_m4S054HL0hyR3CpOk-b7Q7fDX6BuFkgL5OjAExXas,80
-stouputils-1.18.6.dist-info/entry_points.txt,sha256=tx0z9VOnE-sfkmbFbA93zaBMzV3XSsKEJa_BWIqUzxw,57
-stouputils-1.18.6.dist-info/METADATA,sha256=w_R6exClXWoaJI171uO0hX5rZ3oh3hTvCtCua1di9RM,14011
-stouputils-1.18.6.dist-info/RECORD,,
+stouputils-1.19.0.dist-info/WHEEL,sha256=fAguSjoiATBe7TNBkJwOjyL1Tt4wwiaQGtNtjRPNMQA,80
+stouputils-1.19.0.dist-info/entry_points.txt,sha256=tx0z9VOnE-sfkmbFbA93zaBMzV3XSsKEJa_BWIqUzxw,57
+stouputils-1.19.0.dist-info/METADATA,sha256=CsDwe4ywRAflcv8_265i20qTTmt0kWLCwYgPL2kWOo0,14007
+stouputils-1.19.0.dist-info/RECORD,,

{stouputils-1.18.6.dist-info → stouputils-1.19.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.9.27
+Generator: uv 0.9.28
 Root-Is-Purelib: true
 Tag: py3-none-any