require whatsnew & changelog file names and sidebar pages

Author: klmcadams

doc/source/user-guide/options.rst

@@ -309,26 +309,27 @@ to the ``html_theme_options`` dictionary:
     html_theme_options = (
         {
             "whatsnew": {
-                "no_of_headers": 3,
-                "no_of_contents": 3,
-                "whatsnew_file": "whatsnew", # Name of yaml file containing what's new content
-                "changelog_file": "changelog", # Name of changelog file (rst)
-                "pages": ["changelog", ...],
+                "whatsnew_file_name": "whatsnew",
+                "changelog_file_name": "changelog",
+                "sidebar_pages": ["changelog"],
+                "sidebar_no_of_headers": 3,  # Optional
+                "sidebar_no_of_contents": 3,  # Optional
             },
         },
     )
 
 The dictionary contains the following keys:
 
-- ``no_of_headers``: Number of minor version sections to display in the what's new sidebar.
-   By default, it is set to 3.
-- ``no_of_contents``: Number of what's new content to display under each minor version in the
-   what's new sidebar. By default, it displays all dropdowns.
-- ``whatsnew_file``: Name of the YAML file containing what's new content. The YAML file should be
-   in the ``doc/source`` directory.
-- ``changelog_file``: Name of the changelog file (RST) located in the ``doc/source`` directory.
-- ``pages``: List of names for the pages to include the what's new sidebar on. If no value is
-   provided, the what's new sidebar is only displayed in the changelog file.
+- ``whatsnew_file_name``: Name of the YAML file containing what's new content. The YAML file should be
+   in the ``doc/source`` directory. If not provided, the what's new section will not be generated.
+- ``changelog_file_name``: Name of the changelog file (RST) located in the ``doc/source`` directory.
+    If not provided, the what's new section will not be generated.
+- ``sidebar_pages``: List of names for the pages to include the what's new sidebar on. If not
+  provided, the what's new sidebar is not displayed.
+- ``sidebar_no_of_headers``: Number of minor version sections to display in the what's new sidebar.
+   By default, it displays three version sections in the sidebar.
+- ``sidebar_no_of_contents``: Number of what's new content to display under each minor version in the
+   what's new sidebar. If not provided, it displays all dropdowns by default.
 
 The following images show a sample "What's new" section and sidebar in the changelog file:
 

src/ansys_sphinx_theme/__init__.py

@@ -564,30 +564,30 @@ def retrieve_whatsnew_input(app: Sphinx) -> tuple:
     # The source directory of the documentation: {repository_root}/doc/source
     doc_src_dir = app.env.srcdir
 
-    # Get the number of headers to display in the what's new section in the sidebar
-    # By default, it's 3
-    no_of_headers = whatsnew_options.get("no_of_headers", 3)
-    # Get the number of what's new content to display under each minor version in the sidebar.
-    # By default, it's 3
-    no_of_contents = whatsnew_options.get("no_of_contents", None)
-
-    # Get the name of the whatsnew.yml file in doc/source. By default, it's "whatsnew"
-    whatsnew_file = whatsnew_options.get("whatsnew_file", "whatsnew")
+    # Get the name of the whatsnew.yml file in doc/source
+    whatsnew_file = whatsnew_options.get("whatsnew_file_name", None)
     whatsnew_file = pathlib.Path(doc_src_dir) / f"{whatsnew_file}.yml"
 
-    # Get the name of the changelog file in doc/source. By default, it's "changelog"
-    changelog_file = whatsnew_options.get("changelog_file", "changelog")
+    # Get the name of the changelog file in doc/source
+    changelog_file = whatsnew_options.get("changelog_file_name", None)
     changelog_file = pathlib.Path(doc_src_dir) / f"{changelog_file}.rst"
 
-    # Get the pages the whatsnew section should be displayed on. By default, it's changelog
-    pages = whatsnew_options.get("pages", ["changelog"])
+    # Get the pages the whatsnew section should be displayed on
+    pages = whatsnew_options.get("sidebar_pages", None)
+
+    # Get the number of headers to display in the what's new section in the sidebar
+    # By default, it displays the first three minor versions
+    no_of_headers = whatsnew_options.get("sidebar_no_of_headers", 3)
+    # Get the number of what's new content to display under each minor version in the sidebar.
+    # By default, it displays all what's new dropdown titles
+    no_of_contents = whatsnew_options.get("sidebar_no_of_contents", None)
 
     whatsnew_config = {
-        "no_of_headers": no_of_headers,
-        "no_of_contents": no_of_contents,
         "whatsnew_file": whatsnew_file,
         "changelog_file": changelog_file,
         "pages": pages,
+        "no_of_headers": no_of_headers,
+        "no_of_contents": no_of_contents,
     }
 
     return whatsnew_config
@@ -601,6 +601,10 @@ def add_whatsnew_changelog(app, doctree):
     if not whatsnew_config:
         return
 
+    # Skip this function if the what's new file or changelog file were not provided
+    if not whatsnew_config["whatsnew_file"] or not whatsnew_config["changelog_file"]:
+        return
+
     # Read the file and get the sections from the file as a list. For example,
     # sections = [<document: <target...><section "getting started; ref-getting-starte ...>]
     sections = doctree.traverse(nodes.document)
@@ -934,6 +938,15 @@ def extract_whatsnew(app, doctree, docname):
     if not whatsnew_config:
         return
 
+    # Skip this function if the what's new file or changelog file were not provided
+    if not whatsnew_config["whatsnew_file"] or not whatsnew_config["changelog_file"]:
+        return
+
+    # Skip this function if the "sidebar_pages" list is not provided in the whatsnew config
+    if not whatsnew_config["pages"]:
+        return
+
+    # Skip this function if the docname is not in the "sidebar_pages" list
     if docname not in whatsnew_config["pages"]:
         return