Fix(doc): Fix DPF operator doc update of the toc.yml (#2647)

Author: PProfizi

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

@@ -374,8 +374,8 @@ def generate_operator_doc(
         file.write(output)
 
 
-def generate_toc_tree(docs_path: Path):
-    """Write the global toc.yml file for the DPF documentation based on the operators found.
+def update_toc_tree(docs_path: Path):
+    """Update the global toc.yml file for the DPF documentation based on the operators found.
 
     Parameters
     ----------
@@ -391,7 +391,7 @@ def generate_toc_tree(docs_path: Path):
             operators = []  # Reset operators for each category
             for file in folder.iterdir():
                 if (
-                    file.is_file() and file.suffix == ".md"
+                    file.is_file() and file.suffix == ".md" and not file.name.endswith("_upd.md")
                 ):  # Ensure 'file' is a file with .md extension
                     file_name = file.name
                     file_path = f"{category}/{file_name}"
@@ -405,10 +405,18 @@ def generate_toc_tree(docs_path: Path):
         template = jinja2.Template(template_file.read())
     output = template.render(data=data)  # Pass 'data' as a named argument
 
-    # Write the rendered output to toc.yml at the operators_doc level
+    # Update the original toc.yml file with the rendered output for operator_specifications
     toc_path = docs_path / Path("toc.yml")
+    with toc_path.open(mode="r") as file:
+        original_toc = file.read()
+    new_toc = re.sub(
+        pattern=r"- name: Operator specifications\s*.*?(?=- name: Changelog|\Z)",
+        repl=output,
+        string=original_toc,
+        flags=re.DOTALL,
+    )
     with toc_path.open(mode="w") as file:
-        file.write(output)
+        file.write(new_toc)
 
 
 def generate_operators_doc(
@@ -452,7 +460,7 @@ def generate_operators_doc(
     for operator_name in operators:
         generate_operator_doc(server, operator_name, include_private, output_path)
     # Generate the toc tree
-    generate_toc_tree(output_path)
+    update_toc_tree(output_path)
     # Use update files in output_path
     update_operator_descriptions(output_path)
 

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

@@ -1,31 +1,3 @@
-- name: Introduction
-  href: index.md
-- name: Getting started
-  items:
-  - name: Installation
-    href: getting-started/installation.md
-  - name: Licensing
-    href: getting-started/licensing.md
-  - name: Configuration
-    href: getting-started/configuration.md
-- name: User guide
-  items:
-  - name: The server context
-    href: user-guide/server-context.md
-  - name: How to use data containers
-    href: user-guide/using-data-containers.md
-  - name: How to use operators
-    href: user-guide/using-operators.md
-  - name: Workflow examples for beginners
-    href: user-guide/workflow-examples.md
-  - name: Build local documentation
-    href: user-guide/dpf-docs-local-preview.md
-- name: Core concepts
-  items:
-  - name: Available types
-    href: core-concepts/dpf-types.md
-  - name: Operator fundamentals
-    href: core-concepts/operator.md
 - name: Operator specifications
   items:
   - name: Operator specifications
@@ -36,5 +8,4 @@
     - name: {{ operator.operator_name }}
       href: operator-specifications/{{ operator.file_path }}{% endfor %}
   {% endfor %}
-- name: Changelog
-  href: changelog/changelog.md
+

tests/test_documentation.py

@@ -27,16 +27,33 @@
 
 
 def test_generate_operators_doc(tmp_path: Path):
+    specs_path = tmp_path / "operator-specifications"
+    specs_path.mkdir()
+    toc_path = tmp_path / "toc.yml"
+    toc_string = r"""- name: Operator specifications
+  items:
+        
+- name: Changelog
+  href: changelog/changelog.md"""
+    with toc_path.open(mode="w") as ff:
+        ff.write(toc_string)
     generate_operators_doc(ansys_path=dpf.SERVER.ansys_path, output_path=tmp_path, verbose=False)
-    file_to_test = tmp_path / "toc.yml"
-    assert file_to_test.exists()
-    file_to_test = tmp_path / "operator-specifications" / "utility" / "forward.md"
+    assert toc_path.exists()
+    file_to_test = specs_path / "utility" / "forward.md"
     assert file_to_test.exists()
 
 
 def test_generate_operators_doc_plugin_and_update(tmp_path: Path):
     specs_path = tmp_path / "operator-specifications"
     specs_path.mkdir()
+    toc_path = tmp_path / "toc.yml"
+    toc_string = r"""- name: Operator specifications
+  items:
+        
+- name: Changelog
+  href: changelog/changelog.md"""
+    with toc_path.open(mode="w") as ff:
+        ff.write(toc_string)
     utility_path = specs_path / "utility"
     utility_path.mkdir()
     forward_update_path = utility_path / "forward_upd.md"
@@ -51,8 +68,7 @@ def test_generate_operators_doc_plugin_and_update(tmp_path: Path):
         verbose=False,
         desired_plugin="core",
     )
-    file_to_test = tmp_path / "toc.yml"
-    assert file_to_test.exists()
+    assert toc_path.exists()
     file_to_test = utility_path / "forward.md"
     assert file_to_test.exists()
     with file_to_test.open(mode="r", encoding="utf-8") as ff: