Use new "sphinx_toolbox.documentation_summary" module with the docs.

repo-helper · Mar 21, 2021 · 9364bfe · 9364bfe
1 parent dd4110c
commit 9364bfe
Show file tree

Hide file tree

Showing 7 changed files with 17 additions and 11 deletions.
diff --git a/repo_helper/files/docs.py b/repo_helper/files/docs.py
@@ -131,7 +131,7 @@ def compile_target_requirements(self) -> None:
 				"seed-intersphinx-mapping": ">=0.3.1",
 				"default-values": ">=0.4.2",
 				"toctree-plus": ">=0.1.0",
-				"sphinx-toolbox": ">=2.1.0",
+				"sphinx-toolbox": ">=2.2.0",
 				"sphinx-debuginfo": ">=0.1.0",
 				}
 
@@ -354,6 +354,7 @@ def make_conf(repo_path: pathlib.Path, templates: jinja2.Environment) -> List[st
 			"sphinx_toolbox",
 			"sphinx_toolbox.more_autodoc",
 			"sphinx_toolbox.more_autosummary",
+			"sphinx_toolbox.documentation_summary",
 			"sphinx_toolbox.tweaks.param_dash",
 			"sphinx_toolbox.tweaks.latex_toc",
 			"sphinx.ext.intersphinx",
@@ -660,14 +661,15 @@ def rewrite_docs_index(repo_path: pathlib.Path, templates: jinja2.Environment) -
 			templates.globals["repo_name"],
 			)
 
-	short_desc_block = create_short_desc_block(templates.globals["short_desc"], )
-
 	# Do the replacement
 	index_rst = index_rst_file.read_text(encoding="UTF-8")
 	index_rst = shields_regex.sub(shields_block, index_rst)
 	index_rst = installation_regex.sub(install_block, index_rst)
 	index_rst = links_regex.sub(links_block, index_rst)
-	index_rst = short_desc_regex.sub(short_desc_block, index_rst)
+	index_rst = short_desc_regex.sub(
+			".. start short_desc\n\n.. documentation-summary::\n\n.. end short_desc",
+			index_rst,
+			)
 
 	index_rst_file.write_clean(index_rst)
 

diff --git a/repo_helper/templates/conf._py b/repo_helper/templates/conf._py
@@ -87,7 +87,7 @@ add_module_names = False
 hide_none_rtype = True
 all_typevars = True
 overloads_location = "bottom"
-
+documentation_summary = {{ short_desc.__repr__() }}
 
 autodoc_exclude_members = [   # Exclude "standard" methods.
 	"__dict__",

diff --git a/tests/test_files/test_docs.py b/tests/test_files/test_docs.py
@@ -108,7 +108,7 @@ def test_ensure_doc_requirements(tmp_pathplus, demo_environment):
 			"sphinx-notfound-page>=0.5",
 			"sphinx-prompt>=1.1.0",
 			"sphinx-tabs>=1.1.13",
-			"sphinx-toolbox>=2.1.0",
+			"sphinx-toolbox>=2.2.0",
 			"sphinxcontrib-httpdomain>=1.7.0",
 			"sphinxemoji>=0.1.6",
 			"toctree-plus>=0.1.0",
@@ -134,7 +134,7 @@ def test_ensure_doc_requirements(tmp_pathplus, demo_environment):
 			"sphinx-notfound-page>=0.5",
 			"sphinx-prompt>=1.1.0",
 			"sphinx-tabs>=1.1.13",
-			"sphinx-toolbox>=2.1.0",
+			"sphinx-toolbox>=2.2.0",
 			"sphinxcontrib-httpdomain>=1.7.0",
 			"sphinxemoji>=0.1.6",
 			"toctree-plus>=0.1.0",

diff --git a/tests/test_files/test_docs_/test_make_conf_alabaster_._py_ b/tests/test_files/test_docs_/test_make_conf_alabaster_._py_
@@ -34,6 +34,7 @@ extensions = [
 		"sphinx_toolbox",
 		"sphinx_toolbox.more_autodoc",
 		"sphinx_toolbox.more_autosummary",
+		"sphinx_toolbox.documentation_summary",
 		"sphinx_toolbox.tweaks.param_dash",
 		"sphinx_toolbox.tweaks.latex_toc",
 		"sphinx.ext.intersphinx",
@@ -109,7 +110,7 @@ add_module_names = False
 hide_none_rtype = True
 all_typevars = True
 overloads_location = "bottom"
-
+documentation_summary = "a short description"
 
 autodoc_exclude_members = [   # Exclude "standard" methods.
 		"__dict__",

diff --git a/tests/test_files/test_docs_/test_make_conf_domdf_sphinx_theme_._py_ b/tests/test_files/test_docs_/test_make_conf_domdf_sphinx_theme_._py_
@@ -34,6 +34,7 @@ extensions = [
 		"sphinx_toolbox",
 		"sphinx_toolbox.more_autodoc",
 		"sphinx_toolbox.more_autosummary",
+		"sphinx_toolbox.documentation_summary",
 		"sphinx_toolbox.tweaks.param_dash",
 		"sphinx_toolbox.tweaks.latex_toc",
 		"sphinx.ext.intersphinx",
@@ -105,7 +106,7 @@ add_module_names = False
 hide_none_rtype = True
 all_typevars = True
 overloads_location = "bottom"
-
+documentation_summary = "a short description"
 
 autodoc_exclude_members = [   # Exclude "standard" methods.
 		"__dict__",

diff --git a/tests/test_files/test_docs_/test_make_conf_furo_._py_ b/tests/test_files/test_docs_/test_make_conf_furo_._py_
@@ -34,6 +34,7 @@ extensions = [
 		"sphinx_toolbox",
 		"sphinx_toolbox.more_autodoc",
 		"sphinx_toolbox.more_autosummary",
+		"sphinx_toolbox.documentation_summary",
 		"sphinx_toolbox.tweaks.param_dash",
 		"sphinx_toolbox.tweaks.latex_toc",
 		"sphinx.ext.intersphinx",
@@ -110,7 +111,7 @@ add_module_names = False
 hide_none_rtype = True
 all_typevars = True
 overloads_location = "bottom"
-
+documentation_summary = "a short description"
 
 autodoc_exclude_members = [   # Exclude "standard" methods.
 		"__dict__",

diff --git a/tests/test_files/test_docs_/test_make_conf_sphinx_rtd_theme_._py_ b/tests/test_files/test_docs_/test_make_conf_sphinx_rtd_theme_._py_
@@ -34,6 +34,7 @@ extensions = [
 		"sphinx_toolbox",
 		"sphinx_toolbox.more_autodoc",
 		"sphinx_toolbox.more_autosummary",
+		"sphinx_toolbox.documentation_summary",
 		"sphinx_toolbox.tweaks.param_dash",
 		"sphinx_toolbox.tweaks.latex_toc",
 		"sphinx.ext.intersphinx",
@@ -105,7 +106,7 @@ add_module_names = False
 hide_none_rtype = True
 all_typevars = True
 overloads_location = "bottom"
-
+documentation_summary = "a short description"
 
 autodoc_exclude_members = [   # Exclude "standard" methods.
 		"__dict__",