From 5f4a02cc695b7c341872c0255267bddc41218422 Mon Sep 17 00:00:00 2001
From: Michael Panchenko <m.panchenko@appliedai.de>
Date: Tue, 5 Dec 2023 23:24:18 +0100
Subject: [PATCH] Docs: improve API landing page

---
 docs/autogen_rst.py        | 33 ++++++++++++++++++++++++++++++---
 docs/spelling_wordlist.txt |  3 +++
 2 files changed, 33 insertions(+), 3 deletions(-)

diff --git a/docs/autogen_rst.py b/docs/autogen_rst.py
index 26a414f..984604d 100644
--- a/docs/autogen_rst.py
+++ b/docs/autogen_rst.py
@@ -18,7 +18,7 @@ def module_template(module_qualname: str):
 """
 
 
-def index_template(package_name: str, doc_references: list[str] | None = None):
+def index_template(package_name: str, doc_references: list[str] | None = None, text_prefix=""):
     doc_references = doc_references or ""
     if doc_references:
         doc_references = "\n" + "\n".join(f"* :doc:`{ref}`" for ref in doc_references) + "\n"
@@ -27,7 +27,7 @@ def index_template(package_name: str, doc_references: list[str] | None = None):
     title = dirname.replace("_", r"\_")
     if title == "tianshou":
         title = "Tianshou API Reference"
-    return f"{title}\n{'=' * len(title)}" + doc_references
+    return f"{title}\n{'=' * len(title)}" + text_prefix + doc_references
 
 
 def write_to_file(content: str, path: str):
@@ -37,6 +37,14 @@ def write_to_file(content: str, path: str):
     os.chmod(path, 0o666)
 
 
+_SUBTITLE = (
+    "\n Here is the autogenerated documentation of the Tianshou API. \n \n "
+    "The Table of Contents to the left has the same structure as the "
+    "repository's package code. The links at each page point to the submodules and subpackages. \n\n "
+    "Enjoy scrolling through! \n"
+)
+
+
 def make_rst(src_root, rst_root, clean=False, overwrite=False, package_prefix=""):
     """Creates/updates documentation in form of rst files for modules and packages.
 
@@ -59,7 +67,26 @@ def make_rst(src_root, rst_root, clean=False, overwrite=False, package_prefix=""
         shutil.rmtree(rst_root)
 
     base_package_name = package_prefix + os.path.basename(src_root)
-    write_to_file(index_template(base_package_name), os.path.join(rst_root, "index.rst"))
+
+    # TODO: reduce duplication with same logic for subpackages below
+    files_in_dir = os.listdir(src_root)
+    module_names = [f[:-3] for f in files_in_dir if f.endswith(".py") and not f.startswith("_")]
+    subdir_refs = [
+        os.path.join(f, "index")
+        for f in files_in_dir
+        if os.path.isdir(os.path.join(src_root, f)) and not f.startswith("_")
+    ]
+    package_index_rst_path = os.path.join(
+        rst_root,
+        "index.rst",
+    )
+    log.info(f"Writing {package_index_rst_path}")
+    write_to_file(
+        index_template(
+            base_package_name, doc_references=module_names + subdir_refs, text_prefix=_SUBTITLE,
+        ),
+        package_index_rst_path,
+    )
 
     for root, dirnames, filenames in os.walk(src_root):
         if os.path.basename(root).startswith("_"):
diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
index 1645ea3..9066e86 100644
--- a/docs/spelling_wordlist.txt
+++ b/docs/spelling_wordlist.txt
@@ -236,3 +236,6 @@ modelfree
 bdq
 util
 logp
+autogenerated
+subpackage
+subpackages