Rework Doc API Reference (#321)

Co-authored-by: Roberto Pastor Muela <[email protected]>

.gitignore

@@ -164,4 +164,5 @@ test_results*.xml
 mapdl_motorbike_frame.zip
 examples/mapdl_motorbike_frame/task_input_file*
 build_info.*
-doc/source/api/ansys
+doc/source/api/ansys
+doc/source/api/_autosummary

doc/Makefile

@@ -13,26 +13,18 @@ help:
 
 .PHONY: help Makefile
 
-# Install dependencies for sphinx-autoapi
-.install-deps:
-	@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 \
-		pip uninstall --yes sphinx-autoapi; \
-		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
+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
 
 # Customized clean due to examples gallery
-clean: .install-deps
+clean:
 	rm -rf $(BUILDDIR)/*
 	rm -rf $(SOURCEDIR)/examples
 	find . -type d -name "_autosummary" -exec rm -rf {} +

doc/make.bat

@@ -10,13 +10,6 @@ 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
 

doc/source/api/auth.rst

@@ -16,11 +16,20 @@ Authentication function
 
 Auth API
 --------
-.. autoclass:: ansys.hps.client.auth.AuthApi
-   :members:
 
+.. module:: ansys.hps.client.auth.api
 
-User
-----
-.. autoclass:: ansys.hps.client.auth.User
-   :members:
+.. autosummary::
+   :toctree: _autosummary
+
+   AuthApi
+
+Resources
+---------
+
+.. module:: ansys.hps.client.auth
+
+.. autosummary::
+   :toctree: _autosummary
+
+   User

doc/source/api/client.rst

@@ -1,14 +1,18 @@
-
 Client
 ===========================
 
 Connection module
 ------------------------------------------
-.. automodule:: ansys.hps.client.connection
-  :members:
 
+.. module:: ansys.hps.client.connection
+
+.. autosummary::
+   :toctree: _autosummary
+
+   create_session
+   ping
 
 Client object
 ------------------------------------
-.. autoclass:: ansys.hps.client.Client
+.. autoclass:: ansys.hps.client.client.Client
    :members:

doc/source/api/exceptions.rst

@@ -11,8 +11,11 @@ HTTP requests returning an unsuccessful status code raise one of these exception
 All exceptions that a PyHPS client explicitly raises are inherited from the :exc:`ansys.hps.client.HPSError`
 base class.
 
-.. autoexception:: ansys.hps.client.HPSError
-   :members:
-
-.. autoexception:: ansys.hps.client.APIError
-.. autoexception:: ansys.hps.client.ClientError
+.. module:: ansys.hps.client.exceptions
+
+.. autosummary::
+   :toctree: _autosummary
+
+   HPSError
+   APIError
+   ClientError

doc/source/api/index.rst

@@ -7,7 +7,7 @@ This section describes PyHPS functions, classes, methods, and their parameters a
 so that you can understand how to interact with them programmatically.
 
 .. toctree::
-  :maxdepth: 3
+  :maxdepth: 2
 
   client
   auth

doc/source/api/jms.rst

@@ -10,139 +10,44 @@ which is available at ``https://hostname:port/hps/jms/api``.
 APIs
 ----
 
-JMS API
-^^^^^^^
-.. autoclass:: ansys.hps.client.jms.JmsApi
-   :members:
-   :undoc-members:
+.. module:: ansys.hps.client.jms.api
 
-Project API
-^^^^^^^^^^^
-.. autoclass:: ansys.hps.client.jms.ProjectApi
-   :members:
-   :undoc-members:
+.. autosummary::
+   :toctree: _autosummary
 
+   JmsApi
+   ProjectApi
 
 Resources
 ---------
 
-File
-^^^^
-
-.. autoclass:: ansys.hps.client.jms.File
-   :members:
-
-Project
-^^^^^^^
-
-.. autoclass:: ansys.hps.client.jms.Project
-   :members:
-   :undoc-members:
-   :exclude-members: Meta
-
-Fitness definition
-^^^^^^^^^^^^^^^^^^
-
-.. autoclass:: ansys.hps.client.jms.FitnessTermDefinition
-   :members:
-
-.. autoclass:: ansys.hps.client.jms.FitnessDefinition
-   :members:
-
-
-Parameters
-^^^^^^^^^^
-
-.. autoclass:: ansys.hps.client.jms.FloatParameterDefinition
-   :members:
-
-.. autoclass:: ansys.hps.client.jms.BoolParameterDefinition
-   :members:
-
-.. autoclass:: ansys.hps.client.jms.IntParameterDefinition
-   :members:
-
-.. autoclass:: ansys.hps.client.jms.StringParameterDefinition
-   :members:
-
-.. autoclass:: ansys.hps.client.jms.ParameterMapping
-   :members:
-
-Task definition
-^^^^^^^^^^^^^^^
-
-.. autoclass:: ansys.hps.client.jms.Software
-   :members:
-
-.. autoclass:: ansys.hps.client.jms.ResourceRequirements
-   :members:
-
-.. autoclass:: ansys.hps.client.jms.SuccessCriteria
-   :members:
-
-.. autoclass:: ansys.hps.client.jms.Licensing
-   :members:
-
-.. autoclass:: ansys.hps.client.jms.TaskDefinition
-   :members:
-
-
-Job definition
-^^^^^^^^^^^^^^
-
-.. autoclass:: ansys.hps.client.jms.JobDefinition
-   :members:
-   :undoc-members:
-   :exclude-members: Meta
-
-Task
-^^^^
-
-.. autoclass:: ansys.hps.client.jms.Task
-   :members:
-
-
-Job
-^^^
-
-.. autoclass:: ansys.hps.client.jms.Job
-   :members:
-
-
-Job selection
-^^^^^^^^^^^^^
-
-.. autoclass:: ansys.hps.client.jms.JobSelection
-   :members:
-
-
-Design exploration algorithm
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. autoclass:: ansys.hps.client.jms.Algorithm
-   :members:
-
-
-Task definition template
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. autoclass:: ansys.hps.client.jms.TemplateProperty
-   :members:
-
-.. autoclass:: ansys.hps.client.jms.TemplateResourceRequirements
-   :members:
-
-.. autoclass:: ansys.hps.client.jms.TemplateInputFile
-   :members:
-
-.. autoclass:: ansys.hps.client.jms.TemplateOutputFile
-   :members:
-
-.. autoclass:: ansys.hps.client.jms.TaskDefinitionTemplate
-   :members:
-
-Permissions
-^^^^^^^^^^^
-
-.. autoclass:: ansys.hps.client.jms.Permission
-   :members:
+.. module:: ansys.hps.client.jms
+
+.. autosummary::
+   :toctree: _autosummary
+
+   File
+   Project
+   FitnessTermDefinition
+   FitnessDefinition
+   FloatParameterDefinition
+   BoolParameterDefinition
+   IntParameterDefinition
+   StringParameterDefinition
+   ParameterMapping
+   Software
+   ResourceRequirements
+   SuccessCriteria
+   Licensing
+   TaskDefinition
+   JobDefinition
+   Task
+   Job
+   JobSelection
+   Algorithm
+   TemplateProperty
+   TemplateResourceRequirements
+   TemplateInputFile
+   TemplateOutputFile
+   TaskDefinitionTemplate
+   Permission