maint: implementing autoapi and general maintenance (#167)

Author: clatapie

doc/Makefile

@@ -16,11 +16,20 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+# TODO: these lines of code until $(SPHINXBUILD) should be removed once the feature branch is merged
+	pip freeze > temp_req.txt;
+	@if grep -q "sphinx-autoapi @ git+https://github.com/ansys/sphinx-autoapi" temp_req.txt;\
+		then\
+			echo found;\
+		else\
+			pip uninstall --yes sphinx-autoapi;\
+			pip install "sphinx-autoapi @ git+https://github.com/ansys/sphinx-autoapi@feat/single-page-stable";\
+	fi
+	rm temp_req.txt;\
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O);
 
 clean:
 	rm -rf $(BUILDDIR)/*
-	find . -type d -name "_autosummary" -exec rm -rf {} +
 
 pdf:
 	@$(SPHINXBUILD) -M latex "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/make.bat

@@ -10,6 +10,13 @@ if "%SPHINXBUILD%" == "" (
 set SOURCEDIR=source
 set BUILDDIR=_build
 
+REM TODO: these lines of code should be removed once the feature branch is merged
+for /f %%i in ('pip freeze ^| findstr /c:"sphinx-autoapi @ git+https://github.com/ansys/sphinx-autoapi"') do set is_custom_sphinx_autoapi_installed=%%i
+if NOT "%is_custom_sphinx_autoapi_installed%" == "sphinx-autoapi" (
+	pip uninstall --yes sphinx-autoapi
+	pip install "sphinx-autoapi @ git+https://github.com/ansys/sphinx-autoapi@feat/single-page-stable")
+REM TODO: these lines of code should be removed once the feature branch is merged
+
 if "%1" == "" goto help
 if "%1" == "clean" goto clean
 if "%1" == "linkcheck" goto linkcheck

doc/source/api/ast_class.rst

@@ -1,8 +1,14 @@
 """Sphinx documentation configuration file."""
 from datetime import datetime
 import os
-
-from ansys_sphinx_theme import ansys_favicon, get_version_match, pyansys_logo_black
+from pathlib import Path
+
+from ansys_sphinx_theme import (
+    ansys_favicon,
+    get_autoapi_templates_dir_relative_path,
+    get_version_match,
+    pyansys_logo_black,
+)
 from pyconverter.xml2py import __version__
 
 # Project information
@@ -61,7 +67,7 @@
     "jupyter_sphinx",
     "numpydoc",
     "sphinx.ext.autodoc",
-    "sphinx.ext.autosummary",
+    "autoapi.extension",
     "sphinx_autodoc_typehints",
     "sphinx.ext.intersphinx",
     "sphinx.ext.extlinks",
@@ -84,14 +90,16 @@
 # numpydoc configuration
 numpydoc_show_class_members = False
 numpydoc_xref_param_type = True
+numpydoc_xref_param_type = True
+autosectionlabel_prefix_document = True
 
 # Consider enabling numpydoc validation. See:
 # https://numpydoc.readthedocs.io/en/latest/validation.html#
 numpydoc_validate = True
 numpydoc_validation_checks = {
     "GL06",  # Found unknown section
     "GL07",  # Sections are in the wrong order.
-    "GL08",  # The object does not have a docstring
+    # "GL08",  # The object does not have a docstring
     "GL09",  # Deprecation warning should precede extended summary
     "GL10",  # reST directives {directives} must be followed by two colons
     "SS01",  # No summary found
@@ -115,6 +123,36 @@
 # The master toctree document.
 master_doc = "index"
 
+# Configuration for Sphinx autoapi
+autoapi_type = "python"
+autoapi_dirs = ["../../src"]
+autoapi_root = "api"
+autoapi_options = [
+    "members",
+    "undoc-members",
+    "show-inheritance",
+    "show-module-summary",
+    "special-members",
+]
+autoapi_template_dir = get_autoapi_templates_dir_relative_path(Path(__file__))
+suppress_warnings = ["autoapi.python_import_resolution"]
+autoapi_python_use_implicit_namespaces = True
+autoapi_render_in_single_page = ["class", "enum", "exception"]
+
+
+def prepare_jinja_env(jinja_env) -> None:
+    """
+    Customize the jinja env.
+
+    Notes
+    -----
+    See https://jinja.palletsprojects.com/en/3.0.x/api/#jinja2.Environment
+    """
+    jinja_env.globals["project_name"] = project
+
+
+autoapi_prepare_jinja_env = prepare_jinja_env
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #

doc/source/api/ast_functions.rst

@@ -68,7 +68,6 @@ directory by default. This diagram presents the format of the
 
 .. toctree::
     :maxdepth: 1
-    :hidden:
 
     source_code
     objects

doc/source/api/autogenerateddirectory.rst

@@ -2,7 +2,7 @@ XML objects
 ===========
 
 This section describes common objects handled by the converter. It is not
-an exhaustive list. For more information, see :ref:`ref_api`.
+an exhaustive list. For more information, see the API reference section.
 
 Images
 ------

doc/source/api/custom_functions.rst

@@ -62,6 +62,7 @@ doc = [
     "pytest-sphinx==0.5.0",
     "sphinx-autobuild==2021.3.14",
     "sphinx-autodoc-typehints==1.25.2",
+    "sphinx-autoapi==3.0.0", # "sphinx-autoapi @ git+https://github.com/ansys/sphinx-autoapi@feat/single-page-option", ---> Installed directly in workflow
     "sphinx-copybutton==0.5.2",
     "sphinx-notfound-page==1.0.0",
     "sphinx-gallery==0.15.0",

doc/source/api/directory_format.rst

@@ -1,4 +1,4 @@
-# Copyright (c) 2023 ANSYS, Inc. All rights reserved.
+# Copyright (c) 2024 ANSYS, Inc. All rights reserved.
 
 """
 pyconverter.xml2py

doc/source/api/download.rst

@@ -1,4 +1,4 @@
-# Copyright (c) 2023 ANSYS, Inc. All rights reserved.
+# Copyright (c) 2024 ANSYS, Inc. All rights reserved.
 
 import logging
 import re

doc/source/api/index.rst

@@ -1,4 +1,4 @@
-# Copyright (c) 2023 ANSYS, Inc. All rights reserved.
+# Copyright (c) 2024 ANSYS, Inc. All rights reserved.
 
 """Command Line Interface for PyConverter-XML2Py."""
 

doc/source/api/load_xml_doc.rst

@@ -1,4 +1,4 @@
-# Copyright (c) 2023 ANSYS, Inc. All rights reserved.
+# Copyright (c) 2024 ANSYS, Inc. All rights reserved.
 
 import glob
 import os

doc/source/api/oxygen_xml.rst

@@ -1,4 +1,4 @@
-# Copyright (c) 2023 ANSYS, Inc. All rights reserved.
+# Copyright (c) 2024 ANSYS, Inc. All rights reserved.
 
 import argparse
 import os

doc/source/api/writer.rst

@@ -1,3 +1,5 @@
+# Copyright (c) 2024 ANSYS, Inc. All rights reserved.
+
 """Functions to download template datasets from the pyconverter-xml2py repository.
 """