diff --git a/.gitignore b/.gitignore index 98ea197e8..8265fb5f7 100644 --- a/.gitignore +++ b/.gitignore @@ -74,6 +74,7 @@ instance/ # Sphinx documentation doc/_build/ +doc/source/api/ # PyBuilder .pybuilder/ diff --git a/doc/Makefile b/doc/Makefile index 2cd95cff6..2e22043db 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = -j auto +SPHINXOPTS = -j auto -W --keep-going SPHINXBUILD = sphinx-build SOURCEDIR = source BUILDDIR = _build @@ -16,22 +16,13 @@ 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 -# 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); + $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) clean: rm -rf $(BUILDDIR)/* + rm -rf $(SOURCEDIR)/api -pdf: +pdf: Makefile @$(SPHINXBUILD) -M latex "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) cd $(BUILDDIR)/latex && latexmk -r latexmkrc -pdf *.tex -interaction=nonstopmode || true (test -f $(BUILDDIR)/latex/pyconverter-xml2py-Documentation-*.pdf && echo pdf exists) || exit 1 diff --git a/doc/make.bat b/doc/make.bat index 9dd5ed627..fbea3b763 100644 --- a/doc/make.bat +++ b/doc/make.bat @@ -8,17 +8,13 @@ if "%SPHINXBUILD%" == "" ( set SPHINXBUILD=sphinx-build ) set SOURCEDIR=source +set APIDIR=source\api 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 +set SPHINXOPTS=-j auto -W --keep-going if "%1" == "" goto help if "%1" == "clean" goto clean +if "%1" == "pdf" goto pdf if "%1" == "linkcheck" goto linkcheck %SPHINXBUILD% >NUL 2>NUL @@ -38,8 +34,8 @@ if errorlevel 9009 ( 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" +rmdir /s /q %BUILDDIR% > /NUL 2>&1 +rmdir /s /q %APIDIR% > NUL 2>&1 goto end :linkcheck @@ -50,5 +46,17 @@ goto end :help %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +:pdf +%SPHINXBUILD% -M latex %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +cd "%BUILDDIR%\latex" +for %%f in (*.tex) do ( +pdflatex "%%f" --interaction=nonstopmode) +if NOT EXIST pyconverter-xml2py-Documentation-*.pdf ( + Echo "no pdf generated!" + exit /b 1) +Echo "pdf generated!" +goto end + + :end popd diff --git a/doc/source/conf.py b/doc/source/conf.py index 77c9b39b7..758f02c7c 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -138,6 +138,10 @@ suppress_warnings = ["autoapi.python_import_resolution"] autoapi_python_use_implicit_namespaces = True autoapi_render_in_single_page = ["class", "enum", "exception"] +autoapi_own_page_level = "class" +autoapi_keep_files = True +# Generate section labels up to four levels deep +autosectionlabel_maxdepth = 4 def prepare_jinja_env(jinja_env) -> None: diff --git a/pyproject.toml b/pyproject.toml index 5b3c7c3ba..32ce3f3b2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -48,11 +48,11 @@ tests = [ "parse==1.20.1", "pytest==8.1.1", "pytest-cov==4.1.0", - "pytest-rerunfailures==13.0", + "pytest-rerunfailures==14.0", ] doc = [ "Sphinx==7.2.6", - "ansys-sphinx-theme==0.14.0", + "ansys-sphinx-theme==0.14.1", "build>= 0.10.0", "flit>=3.8.0", "jupyter_sphinx==0.5.3", @@ -64,7 +64,7 @@ doc = [ "pytest-sphinx==0.6.0", "sphinx-autobuild==2024.2.4", "sphinx-autodoc-typehints==2.0.0", - "sphinx-autoapi==3.0.0", # "sphinx-autoapi @ git+https://github.com/ansys/sphinx-autoapi@feat/single-page-option", ---> Installed directly in workflow + "sphinx-autoapi==3.1.0a2", "sphinx-copybutton==0.5.2", "sphinx-notfound-page==1.0.0", "sphinx-gallery==0.15.0",