feat(documentation): Add indexes to operator categories in operator documentation sources

Author: PProfizi

src/ansys/dpf/core/documentation/generate_operators_doc.py

@@ -348,7 +348,7 @@ def generate_operator_doc(
     """
     operator_info = fetch_doc_info(server, operator_name)
     scripting_name = operator_info["scripting_info"]["scripting_name"]
-    category = operator_info["scripting_info"]["category"]
+    category: str = operator_info["scripting_info"]["category"]
     if scripting_name:
         file_name = scripting_name
     else:
@@ -391,7 +391,10 @@ def update_toc_tree(docs_path: Path):
             operators = []  # Reset operators for each category
             for file in folder.iterdir():
                 if (
-                    file.is_file() and file.suffix == ".md" and not file.name.endswith("_upd.md")
+                    file.is_file()
+                    and file.suffix == ".md"
+                    and not file.name.endswith("_upd.md")
+                    and not file.name.endswith("_category.md")
                 ):  # Ensure 'file' is a file with .md extension
                     file_name = file.name
                     file_path = f"{category}/{file_name}"
@@ -419,6 +422,60 @@ def update_toc_tree(docs_path: Path):
         file.write(new_toc)
 
 
+def update_categories(docs_path: Path):
+    """Update the category index files for the operator specifications.
+
+    Parameters
+    ----------
+    docs_path:
+        Path to the root of the DPF documentation sources.
+
+    """
+    specs_path = docs_path / Path("operator-specifications")
+    for folder in specs_path.iterdir():
+        if folder.is_dir():  # Ensure 'folder' is a directory
+            category = folder.name
+            operators = []  # Reset operators for each category
+            for file in folder.iterdir():
+                if (
+                    file.is_file()
+                    and file.suffix == ".md"
+                    and not file.name.endswith("_upd.md")
+                    and not file.name.endswith("_category.md")
+                ):  # Ensure 'file' is a file with .md extension
+                    file_name = file.name
+                    operator_name = file_name.replace("_", " ").replace(".md", "")
+                    operators.append({"operator_name": operator_name, "file_path": file_name})
+            # Update category index file
+            category_file_path = folder / f"{category}_category.md"
+            with category_file_path.open(mode="w") as cat_file:
+                cat_file.write(f"# {category.capitalize()} operators\n\n")
+                for operator in operators:
+                    cat_file.write(f"- [{operator['operator_name']}]({operator['file_path']})\n")
+
+
+def update_operator_index(docs_path: Path):
+    """Update the main index file for all operator specifications.
+
+    Parameters
+    ----------
+    docs_path:
+        Path to the root of the DPF documentation sources.
+
+    """
+    specs_path = docs_path / Path("operator-specifications")
+    index_file_path = specs_path / "operator-specifications.md"
+    with index_file_path.open(mode="w") as index_file:
+        index_file.write("# Operator Specifications\n\n")
+        for folder in specs_path.iterdir():
+            if folder.is_dir():  # Ensure 'folder' is a directory
+                category = folder.name
+                index_file.write(
+                    f"## [{category.capitalize()} operators]({category}/{category}_category.md)\n\n"
+                )
+                index_file.write("\n")
+
+
 def generate_operators_doc(
     output_path: Path,
     ansys_path: Path = None,
@@ -461,6 +518,10 @@ def generate_operators_doc(
         generate_operator_doc(server, operator_name, include_private, output_path)
     # Generate the toc tree
     update_toc_tree(output_path)
+    # Generate the category index files
+    update_categories(output_path)
+    # Generate the main index file for all categories
+    update_operator_index(output_path)
     # Use update files in output_path
     update_operator_descriptions(output_path)
 

src/ansys/dpf/core/documentation/toc_template.j2

@@ -4,6 +4,7 @@
     href: operator-specifications/operator-specifications.md
   {% for category in data -%}
   - name: {{ category.category }}
+    href: operator-specifications/{{ category.category }}/{{ category.category }}_category.md
     items:{% for operator in category.operators %}
     - name: {{ operator.operator_name }}
       href: operator-specifications/{{ operator.file_path }}{% endfor %}