feat: add autosummary using jinja to all auto keywords files (#820)

Co-authored-by: pyansys-ci-bot <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

.gitignore

@@ -165,5 +165,3 @@ cython_debug/
 doc/source/examples/
 doc/source/API/_autosummary/
 doc/source/api
-doc/source/keyword_classes/api
-doc/source/keyword_classes/_build/

codegen/generate.py

@@ -186,10 +186,11 @@ def get_keywords_to_generate(kwd_name: typing.Optional[str] = None) -> typing.Li
     return keywords
 
 
-def generate_classes(lib_path: str, kwd_name: typing.Optional[str] = None) -> None:
+def generate_classes(lib_path: str, kwd_name: typing.Optional[str] = None, autodoc_output_path: str = "") -> None:
     """Generates the keyword classes, importer, and type-mapper
     if kwd_name is not None, this only generates that particular keyword class
     """
+    autodoc_entries = []
     env = Environment(loader=get_loader(), trim_blocks=True, lstrip_blocks=True)
     if not os.path.exists(os.path.join(lib_path, "auto")):
         os.mkdir(os.path.join(lib_path, "auto"))
@@ -200,7 +201,16 @@ def generate_classes(lib_path: str, kwd_name: typing.Optional[str] = None) -> No
             continue
         if data_model.is_aliased(name):
             continue
-        generate_class(env, lib_path, item)
+        classname, filename = generate_class(env, lib_path, item)
+        autodoc_entries.append((classname, filename))
+
+    if autodoc_output_path:
+        os.makedirs(autodoc_output_path, exist_ok=True)
+        rst_template = env.get_template("autodoc_rst.jinja")
+        combined_rst = rst_template.render(entries=autodoc_entries)
+        combined_filepath = os.path.join(autodoc_output_path, "index.rst")
+        with open(combined_filepath, "w", encoding="utf-8") as f:
+            f.write(combined_rst)
     keywords_list.extend(get_undefined_alias_keywords(keywords_list))
     if kwd_name == None:
         generate_entrypoints(env, lib_path, keywords_list)
@@ -224,6 +234,12 @@ def load_inputs(this_folder, args):
 def run_codegen(args):
     output = args.output
     this_folder = get_this_folder()
+    autodoc_path = args.autodoc_path
+    if not autodoc_path:
+        autodoc_path = this_folder.parent / "doc" / "source" / "_autosummary"
+    if not os.path.exists(autodoc_path):
+        os.makedirs(autodoc_path)
+    autodoc_path = str(autodoc_path.resolve())
     if args.output == "":
         output = this_folder.parent / "src" / "ansys" / "dyna" / "core" / "keywords" / "keyword_classes"
         output = str(output.resolve())
@@ -232,16 +248,15 @@ def run_codegen(args):
     if args.clean:
         clean(output)
         return
-
     load_inputs(this_folder, args)
     if args.keyword == "":
         kwd = None
         print(f"Generating code for all keywords")
-        generate_classes(output)
+        generate_classes(output, autodoc_output_path=autodoc_path)
     else:
         kwd = args.keyword
         print(f"Generating code for {kwd}")
-        generate_classes(output, kwd)
+        generate_classes(output, kwd, autodoc_output_path=autodoc_path)
 
 
 def parse_args():
@@ -276,6 +291,12 @@ def parse_args():
         default="",
         help="Path to additional cards file, defaults to additional-cards.json in the same folder as this file.",
     )
+    parser.add_argument(
+        "autodoc_path",
+        default="",
+        nargs="?",
+        help="Path to the autodoc output folder. Defaults to doc/source/_autosummary.",
+    )
     return parser.parse_args()
 
 

codegen/keyword_generation/generators/class_generator.py

@@ -376,7 +376,7 @@ def _get_base_variable(classname: str, keyword: str, keyword_options: typing.Dic
     return data
 
 
-def generate_class(env: Environment, lib_path: str, item: typing.Dict) -> None:
+def generate_class(env: Environment, lib_path: str, item: typing.Dict) -> typing.Tuple[str, str]:
     keyword = item["name"]
     fixed_keyword = fix_keyword(keyword)
     classname = item["options"].get("classname", get_classname(fixed_keyword))
@@ -386,6 +386,7 @@ def generate_class(env: Environment, lib_path: str, item: typing.Dict) -> None:
         filename = os.path.join(lib_path, "auto", fixed_keyword.lower() + ".py")
         with open(filename, "w", encoding="utf-8") as f:
             f.write(env.get_template("keyword.j2").render(**jinja_variable))
+        return classname, fixed_keyword.lower()
     except Exception as e:
         print(f"Failure in generating {classname}")
         raise e

codegen/templates/autodoc_rst.jinja

@@ -0,0 +1,14 @@
+.. _autodoc_all:
+
+All Keyword Class Summaries
+###########################
+
+{% for classname, filename in entries %}
+
+{{ classname }}
+{{ "=" * classname|length }}
+
+.. automodule:: ansys.dyna.core.keywords.keyword_classes.auto.{{ filename }} 
+    :members:
+
+{% endfor %}

doc/changelog/820.added.md

@@ -0,0 +1 @@
+add autosummary using jinja to all auto keywords files