fix: Update sphinx autoapi and resolves vale issue (#61)

* fix: test the apidoc * fix: vale issues * fix: makefile * fix: conf.py file * fix: update vale config * fix: revert toml changes * fix: add fn page
ansys · Mar 21, 2024 · 83dd606 · 83dd606
1 parent 0814ad5
commit 83dd606
Show file tree

Hide file tree

Showing 5 changed files with 18 additions and 27 deletions.
diff --git a/doc/.vale.ini b/doc/.vale.ini
@@ -26,9 +26,11 @@ Vocab = ANSYS
 
 # Apply the following styles
 BasedOnStyles = Vale, Google
+Vale.Terms = NO
 
 # Ignore content within inline roles
 TokenIgnores = (:.*:`.*`)|(<.*>)
 
 # Ignoring Google-specific rules - Not applicable under some circumstances
 Google.Colons = NO
+Google.Headings = NO
diff --git a/doc/Makefile b/doc/Makefile
@@ -6,33 +6,27 @@ SPHINXOPTS    = -j auto
 SPHINXBUILD   = sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = _build
+APIDIR        = api
 
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 .PHONY: help Makefile
 
-# Install dependencies for sphinx-autoapi
-.install-deps:
-	@python -m pip freeze | grep -q "sphinx-autoapi @ git+https://github.com/ansys/sphinx-autoapi" && is_custom_sphinx_autoapi_installed="yes" || is_custom_sphinx_autoapi_installed="no"
-	@if [ "$$is_custom_sphinx_autoapi_installed" != "yes" ]; then \
-		python -m pip uninstall --yes sphinx-autoapi; \
-		python -m pip install "sphinx-autoapi @ git+https://github.com/ansys/sphinx-autoapi@feat/single-page-stable"; \
-	fi
-
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: .install-deps Makefile
+%: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-pdf: .install-deps
-	@$(SPHINXBUILD) -M latex "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-	cd $(BUILDDIR)/latex && latexmk -r latexmkrc -pdf *.tex -interaction=nonstopmode || true
-	(test -f $(BUILDDIR)/latex/*.pdf && echo pdf exists) || exit 1
 
 # Customized clean due to examples gallery
-clean: .install-deps
+clean:
 	rm -rf $(BUILDDIR)/*
-	rm -rf $(SOURCEDIR)/examples
-	find . -type d -name "api" -exec rm -rf {} +
+	find . -type d -name $(APIDIR) -exec rm -rf {} +
+
+# Customized pdf for svg format images
+pdf:
+	@$(SPHINXBUILD) -M latex "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	cd $(BUILDDIR)/latex && latexmk -r latexmkrc -pdf *.tex -interaction=nonstopmode || true
+	(test -f $(BUILDDIR)/latex/*.pdf && echo pdf exists) || exit 1
diff --git a/doc/make.bat b/doc/make.bat
@@ -9,13 +9,7 @@ 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" (
-	python -m pip uninstall --yes sphinx-autoapi
-	python -m 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
+set APIDIR=api
 
 if "%1" == "" goto help
 if "%1" == "clean" goto clean
@@ -32,12 +26,13 @@ if errorlevel 9009 (
 	echo.http://sphinx-doc.org/
 	exit /b 1
 )
+
 %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 
 :clean
 rmdir /s /q %BUILDDIR% > /NUL 2>&1
-for /d /r %SOURCEDIR% %%d in (_autosummary) do @if exist "%%d" rmdir /s /q "%%d"
+for /d /r %SOURCEDIR% %%d in (%APIDIR) do @if exist "%%d" rmdir /s /q "%%d"
 goto end
 
 :help

diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -163,7 +163,7 @@ def prepare_jinja_env(jinja_env) -> None:
 suppress_warnings = ["autoapi.python_import_resolution"]
 autoapi_python_use_implicit_namespaces = True
 autoapi_keep_files = True
-autoapi_render_in_single_page = ["class", "enum", "exception", "function"]
+autoapi_own_page_level =  "function"
 #autoapi_python_class_content = "both"
 autoapi_member_order = "alphabetical"
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -39,13 +39,13 @@ tests = [
     "pytest-cov==4.1.0"
 ]
 doc = [
-    "ansys-sphinx-theme==0.13.2",
+    "ansys-sphinx-theme==0.14.1",
     "autodoc_pydantic==2.0.1",
     "jupyter_sphinx==0.5.3",
     "nbsphinx==0.9.3",
     "numpydoc==1.6.0",
     "sphinx==7.2.6",
-    "sphinx-autoapi==3.0.0",
+    "sphinx-autoapi==3.1.a2",
     "sphinx-autodoc-typehints==1.25.3",
     "sphinxcontrib-globalsubs==0.1.1",
     "sphinxcontrib-httpdomain==1.8.1",