From e586f6cdae43b6779934ad32f8fe19c827dac535 Mon Sep 17 00:00:00 2001 From: klmcadams <58492561+klmcadams@users.noreply.github.com> Date: Fri, 7 Jun 2024 16:26:54 -0400 Subject: [PATCH 01/14] add autoapi and docstrings for constants --- doc/source/api/embedding.rst | 23 ------------ doc/source/api/helper.rst | 14 -------- doc/source/api/index.rst | 26 -------------- doc/source/api/logging.rst | 36 ------------------- doc/source/api/mechanical.rst | 27 -------------- doc/source/api/path.rst | 19 ---------- doc/source/api/pool.rst | 21 ----------- doc/source/conf.py | 11 ++++-- doc/source/getting_started/installation.rst | 7 ++-- doc/source/index.rst | 1 + doc/source/user_guide_session/mechanical.rst | 9 ----- doc/source/user_guide_session/pool.rst | 5 --- pyproject.toml | 2 +- src/ansys/mechanical/core/__init__.py | 12 +++++-- src/ansys/mechanical/core/_version.py | 2 +- src/ansys/mechanical/core/embedding/app.py | 2 ++ .../mechanical/core/embedding/initializer.py | 3 ++ .../core/embedding/logger/__init__.py | 3 ++ src/ansys/mechanical/core/errors.py | 1 + src/ansys/mechanical/core/logging.py | 14 +++++++- src/ansys/mechanical/core/mechanical.py | 8 +++++ src/ansys/mechanical/core/run.py | 1 + 22 files changed, 55 insertions(+), 192 deletions(-) delete mode 100644 doc/source/api/embedding.rst delete mode 100644 doc/source/api/helper.rst delete mode 100644 doc/source/api/index.rst delete mode 100644 doc/source/api/logging.rst delete mode 100644 doc/source/api/mechanical.rst delete mode 100644 doc/source/api/path.rst delete mode 100644 doc/source/api/pool.rst delete mode 100644 doc/source/user_guide_session/mechanical.rst diff --git a/doc/source/api/embedding.rst b/doc/source/api/embedding.rst deleted file mode 100644 index d8fe2f4af..000000000 --- a/doc/source/api/embedding.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. _ref_embedding: - -Embedding -========= - -These class and methods provide embedding capability of Mechanical - -.. currentmodule:: ansys.mechanical.core.embedding - -.. autosummary:: - :toctree: _autosummary - - - App - global_variables - Transaction - poster.Poster - logger.Logger - add_mechanical_python_libraries - warnings.connectwarnings - utils.sleep - - diff --git a/doc/source/api/helper.rst b/doc/source/api/helper.rst deleted file mode 100644 index e1ab939db..000000000 --- a/doc/source/api/helper.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _ref_launcher_api: - -Helper functions -================ - -These methods provide helper functions for launching Mechanical, closing Mechanical instances, and automating other tasks. - -.. currentmodule:: ansys.mechanical.core - -.. autosummary:: - :toctree: _autosummary - - launch_mechanical - close_all_local_instances \ No newline at end of file diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst deleted file mode 100644 index 6cc0f3bfa..000000000 --- a/doc/source/api/index.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. _ref_index_api: - -============= -API reference -============= - -This section describes PyMechanical classes, functions, and attributes. - -.. toctree:: - :maxdepth: 2 - :hidden: - - embedding - helper - pool - logging - mechanical - path - -.. toctree:: -- :ref:`ref_embedding` -- :ref:`ref_launcher_api` -- :ref:`ref_pool_api` -- :ref:`ref_logger_api` -- :ref:`ref_mechanical_api` -- :ref:`ref_ansys_tools_path_api` \ No newline at end of file diff --git a/doc/source/api/logging.rst b/doc/source/api/logging.rst deleted file mode 100644 index 9ae30fcfd..000000000 --- a/doc/source/api/logging.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. _ref_logger_api: - -Logging -======= - -To make the logging of events consistent, PyMechanical has a specific -logging architecture with global and local logging instances. - -For these two types of loggers, here is the default format for a log message: - -.. code:: pycon - - >>> from ansys.mechanical.core import launch_mechanical - >>> mechanical = launch_mechanical() - >>> mechanical._log.info("This is an useful message") - LEVEL - INSTANCE NAME - MODULE - FUNCTION - MESSAGE - INFO - GRPC_127.0.0.1:10000 - test - - This is a useful message - -The ``instance_name`` field depends on the name of the Mechanical instance, -which might not be set yet when the log record is created (for -example, during the initialization of the library). If a Mechanical -instance is not yet created, this field might be empty. - -Because both types of loggers are based in the Python ``logging`` module, -you can use any of the tools provided in this module to extend or modify -these loggers. - -``Logger`` class ----------------- - -.. currentmodule:: ansys.mechanical.core.logging - -.. autosummary:: - :toctree: _autosummary - - Logger diff --git a/doc/source/api/mechanical.rst b/doc/source/api/mechanical.rst deleted file mode 100644 index 0106a63bf..000000000 --- a/doc/source/api/mechanical.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. _ref_mechanical_api: - -Mechanical -========== - -This section describes the methods for working with a Mechanical gRPC server using the following class: -:class:`Mechanical ` - -.. currentmodule:: ansys.mechanical.core - -.. autoclass:: ansys.mechanical.core.mechanical.Mechanical - -.. autosummary:: - :toctree: _autosummary - - Mechanical.clear - Mechanical.download - Mechanical.download_project - Mechanical.exit - Mechanical.list_files - Mechanical.log_message - Mechanical.project_directory - Mechanical.run_python_script - Mechanical.run_python_script_from_file - Mechanical.upload - Mechanical.version - diff --git a/doc/source/api/path.rst b/doc/source/api/path.rst deleted file mode 100644 index 6da553638..000000000 --- a/doc/source/api/path.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. _ref_ansys_tools_path_api: - -Ansys path tools -================ - -These methods on the ``ansys-tools-path`` module provide helper functions for configuration and discovery -of the installation path of the Mechanical application. - -.. currentmodule:: ansys.tools.path - -.. autosummary:: - :toctree: _autosummary - - - find_mechanical - get_mechanical_path - change_default_mechanical_path - save_mechanical_path - diff --git a/doc/source/api/pool.rst b/doc/source/api/pool.rst deleted file mode 100644 index f6ab40584..000000000 --- a/doc/source/api/pool.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _ref_pool_api: - -Local Mechanical Pool -===================== - -This section describes how to work with a local pool of Mechanical instances. - -.. currentmodule:: ansys.mechanical.core - -LocalMechanicalPool Class -------------------------- - -:class:`~ansys.mechanical.core.pool.LocalMechanicalPool` provides functionality for working with a local pool of Mechanical instances. - -.. autoclass:: ansys.mechanical.core.pool.LocalMechanicalPool - -.. autosummary:: - :toctree: _autosummary - - pool.LocalMechanicalPool - diff --git a/doc/source/conf.py b/doc/source/conf.py index 4ea1a8ef2..2c27988f1 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -37,7 +37,7 @@ copyright = f"(c) {datetime.now().year} ANSYS, Inc. All rights reserved" author = "ANSYS Inc." release = version = pymechanical.__version__ -cname = os.getenv("DOCUMENTATION_CNAME", default="nocname.com") +cname = os.getenv("DOCUMENTATION_CNAME", default="mechanical.docs.pyansys.com") # Add any Sphinx extension module names here, as strings. They can be @@ -46,6 +46,7 @@ # -- General configuration --------------------------------------------------- # Sphinx extensions extensions = [ + "ansys_sphinx_theme.extension.autoapi", "jupyter_sphinx", "notfound.extension", "numpydoc", @@ -72,7 +73,7 @@ "pypim": ("https://pypim.docs.pyansys.com/version/dev/", None), } -suppress_warnings = ["label.*"] +suppress_warnings = ["label.*", "autoapi.python_import_resolution", "design.grid", "config.cache"] # supress_warnings = ["ref.option"] @@ -84,7 +85,7 @@ 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 @@ -220,6 +221,10 @@ "thumbnail": "https://cheatsheets.docs.pyansys.com/pymechanical_cheat_sheet.png", "needs_download": True, }, + "ansys_sphinx_theme_autoapi": { + "project": project, + }, + "navigation_depth": 10 } # -- Options for HTMLHelp output --------------------------------------------- diff --git a/doc/source/getting_started/installation.rst b/doc/source/getting_started/installation.rst index 9e9a119e1..5d71fa56a 100644 --- a/doc/source/getting_started/installation.rst +++ b/doc/source/getting_started/installation.rst @@ -77,7 +77,6 @@ This package is required to use PyMechanical. If you install Ansys in a directory other than the default or typical location, you can save this directory path using the ``save_mechanical_path`` function. Then use ``get_mechanical_path`` and ``version_from_path`` functions to verify the path and version. -For more details, refer to the :ref:`ref_ansys_tools_path_api`. .. code:: pycon @@ -108,8 +107,7 @@ Verify your installation by starting a remote session of Mechanical from Python: Software build date:Wednesday, August 10, 2022 4:28:15 PM If you see a response from the server, you can begin using Mechanical -as a service. For information on the PyMechanical interface, see -:ref:`ref_mechanical_user_guide`. +as a service. Verify an embedded instance ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -139,3 +137,6 @@ Inside of Python, use the following commands to load an embedded instance: Product Version:232 Software build date: 05/30/2023 15:25:53 +.. LINKS AND REFERENCES +.. _ansys_tools_path_api: https://github.com/psf/black +.. _flake8: https://flake8.pycqa.org/en/latest/ diff --git a/doc/source/index.rst b/doc/source/index.rst index e4f33cecf..b6b37f071 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -47,6 +47,7 @@ user_guide_session/index user_guide_embedding/index user_guide_scripting/index + architecture api/index contributing diff --git a/doc/source/user_guide_session/mechanical.rst b/doc/source/user_guide_session/mechanical.rst deleted file mode 100644 index b112a60f4..000000000 --- a/doc/source/user_guide_session/mechanical.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _ref_mechanical_user_guide: - -PyMechanical usage -================== - -This page provides an overview of the -:class:`Mechanical ` class. - -For more information on this class, see :ref:`ref_mechanical_api`. diff --git a/doc/source/user_guide_session/pool.rst b/doc/source/user_guide_session/pool.rst index 500880146..3487a87cb 100644 --- a/doc/source/user_guide_session/pool.rst +++ b/doc/source/user_guide_session/pool.rst @@ -81,8 +81,3 @@ each instance of Mechanical over a set of input files. 'result7', 'result8', 'result9'] - -API reference -------------- - -For more information, see :ref:`ref_pool_api`. diff --git a/pyproject.toml b/pyproject.toml index 19cf5f629..db7d74440 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -56,7 +56,7 @@ tests = [ ] doc = [ "sphinx==7.3.7", - "ansys-sphinx-theme==0.16.5", + "ansys-sphinx-theme[autoapi]==0.16.5", "grpcio==1.64.0", "imageio-ffmpeg==0.5.1", "imageio==2.34.1", diff --git a/src/ansys/mechanical/core/__init__.py b/src/ansys/mechanical/core/__init__.py index 3ac7233e6..b16c3c325 100644 --- a/src/ansys/mechanical/core/__init__.py +++ b/src/ansys/mechanical/core/__init__.py @@ -27,19 +27,23 @@ from ansys.tools.path import find_mechanical import appdirs -# Setup data directory USER_DATA_PATH = appdirs.user_data_dir(appname="ansys_mechanical_core", appauthor="Ansys") +"""User data directory.""" + if not os.path.exists(USER_DATA_PATH): os.makedirs(USER_DATA_PATH) EXAMPLES_PATH = os.path.join(USER_DATA_PATH, "examples") +"""Examples path.""" + if not os.path.exists(EXAMPLES_PATH): os.makedirs(EXAMPLES_PATH) from ansys.mechanical.core.logging import Logger -# Create logger for package level use LOG = Logger(level=logging.ERROR, to_file=False, to_stdout=True) +"""Create logger for package level use.""" + LOG.debug("Loaded logging module as LOG") from ansys.mechanical.core._version import __version__ @@ -57,12 +61,14 @@ from ansys.mechanical.core.embedding import App, global_variables HAS_EMBEDDING = True + """Whether or not Mechanical embedding is being used.""" except: HAS_EMBEDDING = False -# manage the package level ports LOCAL_PORTS = [] +"""Manage the package level ports.""" from ansys.mechanical.core.pool import LocalMechanicalPool BUILDING_GALLERY = False +"""Whether or not to build gallery examples.""" diff --git a/src/ansys/mechanical/core/_version.py b/src/ansys/mechanical/core/_version.py index 8576dc2f1..93dd8fc9b 100644 --- a/src/ansys/mechanical/core/_version.py +++ b/src/ansys/mechanical/core/_version.py @@ -39,9 +39,9 @@ # major, minor, patch __version__ = importlib_metadata.version("ansys-mechanical-core") -# In descending order SUPPORTED_MECHANICAL_VERSIONS = { 241: "2024R1", 232: "2023R2", 231: "2023R1", } +"""Supported mechanical versions in descending order.""" diff --git a/src/ansys/mechanical/core/embedding/app.py b/src/ansys/mechanical/core/embedding/app.py index d9f3148ae..8cd642130 100644 --- a/src/ansys/mechanical/core/embedding/app.py +++ b/src/ansys/mechanical/core/embedding/app.py @@ -35,6 +35,7 @@ import pyvista # noqa: F401 HAS_PYVISTA = True + """Whether or not PyVista exists.""" except: HAS_PYVISTA = False @@ -46,6 +47,7 @@ def _get_default_addin_configuration() -> AddinConfiguration: INSTANCES = [] +"""List of instances.""" def _dispose_embedded_app(instances): # pragma: nocover diff --git a/src/ansys/mechanical/core/embedding/initializer.py b/src/ansys/mechanical/core/embedding/initializer.py index f0197e8ee..c92dcd3df 100644 --- a/src/ansys/mechanical/core/embedding/initializer.py +++ b/src/ansys/mechanical/core/embedding/initializer.py @@ -34,7 +34,10 @@ from ansys.mechanical.core.embedding.resolver import resolve INITIALIZED_VERSION = None +"""Constant for the initialized version.""" + SUPPORTED_MECHANICAL_EMBEDDING_VERSIONS_WINDOWS = {241: "2024R1", 232: "2023R2", 231: "2023R1"} +"""Supported Mechanical embedding versions on Windows.""" def __add_sys_path(version: int) -> str: diff --git a/src/ansys/mechanical/core/embedding/logger/__init__.py b/src/ansys/mechanical/core/embedding/logger/__init__.py index 2d6cd2cde..7d17291da 100644 --- a/src/ansys/mechanical/core/embedding/logger/__init__.py +++ b/src/ansys/mechanical/core/embedding/logger/__init__.py @@ -56,7 +56,10 @@ from ansys.mechanical.core.embedding.logger import environ, linux_api, sinks, windows_api LOGGING_SINKS: typing.Set[int] = set() +"""Constant for logging sinks.""" + LOGGING_CONTEXT: str = "PYMECHANICAL" +"""Constant for logging context.""" def _get_backend() -> ( diff --git a/src/ansys/mechanical/core/errors.py b/src/ansys/mechanical/core/errors.py index d4e18e6d0..42345976f 100644 --- a/src/ansys/mechanical/core/errors.py +++ b/src/ansys/mechanical/core/errors.py @@ -31,6 +31,7 @@ from ansys.mechanical.core import LOG as logger SIGINT_TRACKER = [] +"""List of SIGINT keyboard interrupts.""" class VersionError(ValueError): diff --git a/src/ansys/mechanical/core/logging.py b/src/ansys/mechanical/core/logging.py index 7a7007a11..528b532ab 100644 --- a/src/ansys/mechanical/core/logging.py +++ b/src/ansys/mechanical/core/logging.py @@ -138,30 +138,42 @@ # Default configuration LOG_LEVEL = logging.DEBUG +"""Default log level configuration.""" FILE_NAME = "pymechanical.log" +"""Default file name.""" # For convenience DEBUG = logging.DEBUG +"""Constant for logging.DEBUG.""" INFO = logging.INFO +"""Constant for logging.INFO.""" WARN = logging.WARN +"""Constant for logging.WARN.""" ERROR = logging.ERROR +"""Constant for logging.ERROR.""" CRITICAL = logging.CRITICAL +"""Constant for logging.CRITICAL.""" # Formatting - STDOUT_MSG_FORMAT = "%(levelname)s - %(instance_name)s - %(module)s - %(funcName)s - %(message)s" +"""Standard output message format.""" FILE_MSG_FORMAT = STDOUT_MSG_FORMAT +"""File message format.""" DEFAULT_STDOUT_HEADER = """ LEVEL - INSTANCE NAME - MODULE - FUNCTION - MESSAGE """ +"""Default standard output header.""" + DEFAULT_FILE_HEADER = DEFAULT_STDOUT_HEADER +"""Default file header.""" NEW_SESSION_HEADER = f""" =============================================================================== NEW SESSION - {datetime.now().strftime("%m/%d/%Y, %H:%M:%S")} ===============================================================================""" +"""Default new session header containing date and time.""" string_to_loglevel = { "DEBUG": logging.DEBUG, diff --git a/src/ansys/mechanical/core/mechanical.py b/src/ansys/mechanical/core/mechanical.py index 7b4ffc779..4d9b25d87 100644 --- a/src/ansys/mechanical/core/mechanical.py +++ b/src/ansys/mechanical/core/mechanical.py @@ -63,15 +63,19 @@ from tqdm import tqdm _HAS_TQDM = True + """Whether or not tqdm is installed.""" except ModuleNotFoundError: # pragma: no cover _HAS_TQDM = False # Default 256 MB message length MAX_MESSAGE_LENGTH = int(os.environ.get("PYMECHANICAL_MAX_MESSAGE_LENGTH", 256 * 1024**2)) +"""Default message length.""" # Chunk sizes for streaming and file streaming DEFAULT_CHUNK_SIZE = 256 * 1024 # 256 kB +"""Default chunk size.""" DEFAULT_FILE_CHUNK_SIZE = 1024 * 1024 # 1MB +"""Default file chunk size.""" def setup_logger(loglevel="INFO", log_file=True, mechanical_instance=None): @@ -112,9 +116,13 @@ def wrapper(*args, **kwargs): LOCALHOST = "127.0.0.1" +"""Localhost address.""" + MECHANICAL_DEFAULT_PORT = 10000 +"""Default Mechanical port.""" GALLERY_INSTANCE = [None] +"""List of gallery instances.""" def _cleanup_gallery_instance(): # pragma: no cover diff --git a/src/ansys/mechanical/core/run.py b/src/ansys/mechanical/core/run.py index d8cba9513..87565d1e6 100644 --- a/src/ansys/mechanical/core/run.py +++ b/src/ansys/mechanical/core/run.py @@ -36,6 +36,7 @@ from ansys.mechanical.core.feature_flags import get_command_line_arguments, get_feature_flag_names DRY_RUN = False +"""Dry run constant.""" # TODO - add logging options (reuse env var based logging initialization) # TODO - add timeout From 92bc5898470b6aa8b81cfc444a719ffe362d2fcf Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 7 Jun 2024 20:33:31 +0000 Subject: [PATCH 02/14] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- doc/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 2c27988f1..644fd75ae 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -224,7 +224,7 @@ "ansys_sphinx_theme_autoapi": { "project": project, }, - "navigation_depth": 10 + "navigation_depth": 10, } # -- Options for HTMLHelp output --------------------------------------------- From a5dafcb6f1892557ec387bfe60c83ac91185138b Mon Sep 17 00:00:00 2001 From: pyansys-ci-bot Date: Fri, 7 Jun 2024 20:34:58 +0000 Subject: [PATCH 03/14] Adding changelog entry: 761.added.md --- doc/changelog.d/761.added.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 doc/changelog.d/761.added.md diff --git a/doc/changelog.d/761.added.md b/doc/changelog.d/761.added.md new file mode 100644 index 000000000..1143ac838 --- /dev/null +++ b/doc/changelog.d/761.added.md @@ -0,0 +1 @@ +feat: implement autoapi \ No newline at end of file From 8c6043ff6884535b188571cecf7ab0620171ee5e Mon Sep 17 00:00:00 2001 From: klmcadams <58492561+klmcadams@users.noreply.github.com> Date: Thu, 13 Jun 2024 11:58:47 -0400 Subject: [PATCH 04/14] update changelog and remove architecture from index --- CHANGELOG.md | 2 +- doc/source/index.rst | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ed3238538..53b06438d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,4 +4,4 @@ This project uses [towncrier](https://towncrier.readthedocs.io/) to generate the Refer to the [raw release notes](doc/source/changelog.rst) for more information. -[Published release notes](https://mechanical.docs.pyansys.com/version/stable/changelog.html) can be found in the online documentation. \ No newline at end of file +[Release notes](https://mechanical.docs.pyansys.com/version/stable/changelog.html) can be found in the online documentation. \ No newline at end of file diff --git a/doc/source/index.rst b/doc/source/index.rst index 154f37411..55354e03f 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -47,7 +47,6 @@ user_guide_session/index user_guide_embedding/index user_guide_scripting/index - architecture api/index contributing changelog From bcdd46b9417774cd103d673e80610f74c30926f5 Mon Sep 17 00:00:00 2001 From: klmcadams <58492561+klmcadams@users.noreply.github.com> Date: Thu, 13 Jun 2024 16:05:27 -0400 Subject: [PATCH 05/14] update links and add path.rst file --- doc/source/ansys_tools_path_api/path.rst | 18 ++++++++++++++++++ doc/source/conf.py | 3 +++ doc/source/getting_started/faq.rst | 4 ++-- .../getting_started/running_mechanical.rst | 12 ++++++------ .../user_guide_embedding/configuration.rst | 4 ++-- doc/source/user_guide_embedding/index.rst | 8 ++++---- doc/source/user_guide_embedding/logging.rst | 4 ++-- doc/source/user_guide_session/index.rst | 9 ++++----- doc/source/user_guide_session/pool.rst | 10 +++++----- .../user_guide_session/server-launcher.rst | 4 ++-- 10 files changed, 48 insertions(+), 28 deletions(-) create mode 100644 doc/source/ansys_tools_path_api/path.rst diff --git a/doc/source/ansys_tools_path_api/path.rst b/doc/source/ansys_tools_path_api/path.rst new file mode 100644 index 000000000..6529485aa --- /dev/null +++ b/doc/source/ansys_tools_path_api/path.rst @@ -0,0 +1,18 @@ +.._ref_ansys_tools_path_api + +Ansys path tools +================ + +These methods on the ``ansys-tools-path`` module provide helper functions for configuration and discovery +of the installation path of the Mechanical application. + +.. currentmodule:: ansys.tools.path + +.. autosummary:: + :toctree: _autosummary + + + find_mechanical + get_mechanical_path + change_default_mechanical_path + save_mechanical_path \ No newline at end of file diff --git a/doc/source/conf.py b/doc/source/conf.py index 82ca2ef82..7f2036fd3 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -227,6 +227,8 @@ "navigation_depth": 10, } +autoapi_template_dir = "_autoapi_templates" + # -- Options for HTMLHelp output --------------------------------------------- # Output file base name for HTML help builder. @@ -303,6 +305,7 @@ "https://ansysaccount.b2clogin.com/*", "https://answers.microsoft.com/en-us/windows/forum/all/*", "https://download.ansys.com/*", + "https://mechanical.docs.pyansys.com/version/stable/api/*", # Remove this after release 0.10.12 ] linkcheck_anchors = False diff --git a/doc/source/getting_started/faq.rst b/doc/source/getting_started/faq.rst index fbc196258..fe5074335 100644 --- a/doc/source/getting_started/faq.rst +++ b/doc/source/getting_started/faq.rst @@ -93,8 +93,8 @@ The way that you clear all data from Mechanical in PyMechanical depends on if Mechanical is a remote session or embedded. - If Mechanical is a remote session, use either the - :func:`Mechanical.clear() ` + `Mechanical.clear() `_ method or exit and restart Mechanical. - If Mechanical is embedded, use the - :func:`app.new() ` + `app.new() `_ method. diff --git a/doc/source/getting_started/running_mechanical.rst b/doc/source/getting_started/running_mechanical.rst index c82ccf15b..36199979c 100644 --- a/doc/source/getting_started/running_mechanical.rst +++ b/doc/source/getting_started/running_mechanical.rst @@ -32,9 +32,9 @@ Launch Mechanical on the local machine using Python ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When Mechanical is installed locally on your machine, you can use the -:func:`launch_mechanical() ` method to launch and automatically connect to -Mechanical. While this method provides the easiest and fastest way to launch Mechanical, it only works with a local -Mechanical installation. +`launch_mechanical() `_ +method to launch and automatically connect to Mechanical. While this method provides the +easiest and fastest way to launch Mechanical, it only works with a local Mechanical installation. Launch Mechanical locally with this code: @@ -49,7 +49,7 @@ Launch Mechanical locally with this code: Software build date:Wednesday, August 10, 2022 4:28:15 PM Launch Mechanical from the command line -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The `ansys-mechanical` utility is installed automatically with PyMechanical, and can be used to run Mechanical from the command line. To obtain help on @@ -160,7 +160,7 @@ Manually set the location of the executable file If you have a non-standard installation of Mechanical, PyMechanical might not be able to find your installation. In this case, you should manually set the location of your Mechanical executable file as the first parameter -for the :func:`launch_mechanical() ` method. +for the `launch_mechanical()`_ method. **On Windows** @@ -180,7 +180,7 @@ for the :func:`launch_mechanical() ` me exec_loc = "/usr/ansys_inc/v231/aisol/.workbench" mechanical = launch_mechanical(exec_loc) -If, when using the :func:`launch_mechanical() ` +If, when using the `launch_mechanical()`_ method, Mechanical still fails to launch or hangs while launching, pass the ``verbose_mechanical=True`` parameter. This prints the output of Mechanical in the Python console. You can then use this output to debug why Mechanical isn't launching. diff --git a/doc/source/user_guide_embedding/configuration.rst b/doc/source/user_guide_embedding/configuration.rst index cb83df415..5058c8d62 100644 --- a/doc/source/user_guide_embedding/configuration.rst +++ b/doc/source/user_guide_embedding/configuration.rst @@ -5,9 +5,9 @@ Addin configuration There are some configuration options that are respected when loading an embedded instance of Mechanical into python. -The class :class:`Configuration ` can be +The class `Configuration `_ can be used to set up Addin configuration. This configuration can be supplied to the constructor -of the class :class:`Configuration `. +of the class `App `_. For example, to load an instance of Mechanical using the "Mechanical" configuration name and without loading any ACT Addins: diff --git a/doc/source/user_guide_embedding/index.rst b/doc/source/user_guide_embedding/index.rst index 2de7cd454..4c32cb46b 100644 --- a/doc/source/user_guide_embedding/index.rst +++ b/doc/source/user_guide_embedding/index.rst @@ -22,7 +22,7 @@ an instance of Mechanical in Python. Overview -------- -The :class:`Application ` class provides +The `App `_ class provides a Mechanical instance: .. code:: python @@ -32,8 +32,8 @@ a Mechanical instance: app = App() ns = app.DataModel.Project.Model.AddNamedSelection() -The :class:`Application ` class has access -to the global scripting entry points that are available from built-in Mechanical scripting: +The `App`_ class has access to the global scripting entry points that are +available from built-in Mechanical scripting: * ExtAPI: ``Application.ExtAPI`` * DataModel: ``Application.DataModel`` @@ -48,7 +48,7 @@ namespaces, and types, see :ref:`ref_embedding_user_guide_globals`. Additional configuration ------------------------ -By default, an instance of the :class:`Application ` class +By default, an instance of the `App`_ class uses the same Addin configuration as standalone Mechanical. To customize Addins, see :ref:`ref_embedding_user_guide_addin_configuration`. diff --git a/doc/source/user_guide_embedding/logging.rst b/doc/source/user_guide_embedding/logging.rst index aeffeb98f..8ade37b3d 100644 --- a/doc/source/user_guide_embedding/logging.rst +++ b/doc/source/user_guide_embedding/logging.rst @@ -8,7 +8,7 @@ enabled by setting environment variables before starting Mechanical. With PyMech it is possible to configure logging at any time, whether it is before or after creating the embedded application, using the same Python API. -Use the :class:`Configuration ` class to +Use the `Configuration `_ class to configure logging to the standard output for all warning messages and above (which are error and fatal messages). For example: @@ -22,7 +22,7 @@ For example: _ = mech.App() After the embedded application has been created, you can write messages to the same -log using the :class:`Logger ` class like this: +log using the `Logger ` class like this: .. code:: python diff --git a/doc/source/user_guide_session/index.rst b/doc/source/user_guide_session/index.rst index 9935fcebb..0d67ec211 100644 --- a/doc/source/user_guide_session/index.rst +++ b/doc/source/user_guide_session/index.rst @@ -21,14 +21,13 @@ to a remote Mechanical session. Overview -------- -The :func:`launch_mechanical() ` method -creates an instance of the :class:`Mechanical ` +The `launch_mechanical() `_ method +creates an instance of the `Mechanical `_ class in the background and sends commands to it as a service. Because errors and warnings are processed Pythonically, you can develop a script in real time without worrying about whether the script runs correctly when deployed in batch mode. -Here is how you use the :func:`launch_mechanical() ` -method to launch Mechanical from Python in gRPC mode: +Here is how you use the `launch_mechanical()`_ method to launch Mechanical from Python in gRPC mode: .. code:: python @@ -62,7 +61,7 @@ Python, run them interactively, and then run them in batch without worrying if t scripts run correctly. This would not be the case if you had instead outputted the scripts that you wrote to script files. -The :class:`Mechanical ` class supports +The `Mechanical`_ class supports much more than sending text to Mechanical. It includes higher-level wrapping that provides for better scripting and interaction with Mechanical. For information on advanced methods for interacting with Mechanical, see :ref:`ref_examples`. diff --git a/doc/source/user_guide_session/pool.rst b/doc/source/user_guide_session/pool.rst index 3487a87cb..be4a51e6b 100644 --- a/doc/source/user_guide_session/pool.rst +++ b/doc/source/user_guide_session/pool.rst @@ -1,9 +1,9 @@ Create a pool of Mechanical servers =================================== -The :class:`LocalMechanicalPool ` +The `LocalMechanicalPool `_ class simplifies creating and connecting to multiple servers of the -:class:`Mechanical ` class for batch +`Mechanical `_ class for batch processing. You can use this class for batch processing a set of input files or other batch-related processes. @@ -40,7 +40,7 @@ Run a set of input files ------------------------ You can use the pool to run a set of pre-generated input files using the -:func:`run_batch() ` method. +`run_batch() `_ method. For example, you can run the first set of 20 verification files with this code: @@ -55,9 +55,9 @@ For example, you can run the first set of 20 verification files with this code: Run a user-defined function --------------------------- -While the previous example uses the :func:`run_batch() ` +While the previous example uses the `run_batch()`_ method to run a set of inputs files, you can also use the -:func:`map() ` method to run a custom user-defined function on +`map() `_ method to run a custom user-defined function on each instance of Mechanical over a set of input files. .. code:: pycon diff --git a/doc/source/user_guide_session/server-launcher.rst b/doc/source/user_guide_session/server-launcher.rst index 78415ed85..4ad57017d 100644 --- a/doc/source/user_guide_session/server-launcher.rst +++ b/doc/source/user_guide_session/server-launcher.rst @@ -6,7 +6,7 @@ Most of the time, PyMechanical can determine this location automatically. Howeve if you have a non-standard installation, you must provide this location. To test and set up your installation of PyMechanical, run the -:func:`launch_mechanical() ` +`launch_mechanical() `_ method: .. code:: python @@ -80,4 +80,4 @@ You can use the ``additional_switches`` keyword argument to specify additional a API reference ~~~~~~~~~~~~~ For more information on controlling how Mechanical launches locally, see the -:func:`launch_mechanical() ` method. +`launch_mechanical()`_ method. From 2e39a0b637cce9f953da65229c88dae7837256b9 Mon Sep 17 00:00:00 2001 From: klmcadams <58492561+klmcadams@users.noreply.github.com> Date: Thu, 13 Jun 2024 16:08:22 -0400 Subject: [PATCH 06/14] fix spacing --- doc/source/ansys_tools_path_api/path.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/ansys_tools_path_api/path.rst b/doc/source/ansys_tools_path_api/path.rst index 6529485aa..37351b7f7 100644 --- a/doc/source/ansys_tools_path_api/path.rst +++ b/doc/source/ansys_tools_path_api/path.rst @@ -1,4 +1,4 @@ -.._ref_ansys_tools_path_api +.. _ref_ansys_tools_path_api: Ansys path tools ================ From f81f5c173717fb660b8278301b28db19277c255f Mon Sep 17 00:00:00 2001 From: klmcadams <58492561+klmcadams@users.noreply.github.com> Date: Thu, 13 Jun 2024 16:11:49 -0400 Subject: [PATCH 07/14] remove autoapi_template_dir from file --- doc/source/conf.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 7f2036fd3..9adeba310 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -227,8 +227,6 @@ "navigation_depth": 10, } -autoapi_template_dir = "_autoapi_templates" - # -- Options for HTMLHelp output --------------------------------------------- # Output file base name for HTML help builder. From 2f7396dee17afb4071a25895da07c32211af0466 Mon Sep 17 00:00:00 2001 From: klmcadams <58492561+klmcadams@users.noreply.github.com> Date: Fri, 14 Jun 2024 08:54:40 -0400 Subject: [PATCH 08/14] use autoapi template --- doc/source/_templates/autoapi/index.rst | 16 ++ .../_templates/autoapi/python/class.rst | 222 +++++++++++++++ .../_templates/autoapi/python/module.rst | 252 ++++++++++++++++++ .../{ansys_tools_path_api => api}/path.rst | 0 doc/source/conf.py | 4 +- doc/source/getting_started/installation.rst | 7 +- .../user_guide_session/server-launcher.rst | 4 +- 7 files changed, 498 insertions(+), 7 deletions(-) create mode 100644 doc/source/_templates/autoapi/index.rst create mode 100644 doc/source/_templates/autoapi/python/class.rst create mode 100644 doc/source/_templates/autoapi/python/module.rst rename doc/source/{ansys_tools_path_api => api}/path.rst (100%) diff --git a/doc/source/_templates/autoapi/index.rst b/doc/source/_templates/autoapi/index.rst new file mode 100644 index 000000000..b4a23cf2e --- /dev/null +++ b/doc/source/_templates/autoapi/index.rst @@ -0,0 +1,16 @@ +API reference +============= + +This section describes {{ project_name }} endpoints, their capabilities, and how +to interact with them programmatically. See the API reference for ``ansys-tools-path`` +`here `_. + +.. toctree:: + :titlesonly: + :maxdepth: 3 + + {% for page in pages %} + {% if (page.top_level_object or page.name.split('.') | length == 3) and page.display %} + {{ page.name }}<{{ page.include_path }}> + {% endif %} + {% endfor %} \ No newline at end of file diff --git a/doc/source/_templates/autoapi/python/class.rst b/doc/source/_templates/autoapi/python/class.rst new file mode 100644 index 000000000..0a13e066a --- /dev/null +++ b/doc/source/_templates/autoapi/python/class.rst @@ -0,0 +1,222 @@ +{% if obj.display %} + +{# ----------------- Start macros definition for tab item ------------------#} +{% macro tab_item_from_objects_list(objects_list, title="") -%} + + .. tab-item:: {{ title }} + + .. list-table:: + :header-rows: 0 + :widths: auto + + {% for obj in objects_list %} + * - :py:attr:`~{{ obj.name }}` + - {{ obj.summary }} + {% endfor %} +{%- endmacro %} +{# --------------------------- End macros definition ----------------------- #} + + {% if is_own_page %} +:class:`{{ obj.name }}` +========={{ "=" * obj.name | length }} + + {% endif %} + {% set visible_children = obj.children|selectattr("display")|list %} + {% set own_page_children = visible_children|selectattr("type", "in", own_page_types)|list %} + {% if is_own_page and own_page_children %} +.. toctree:: + :hidden: + + {% for child in own_page_children %} + {{ child.include_path }} + {% endfor %} + + {% endif %} +.. py:{{ obj.type }}:: {% if is_own_page %}{{ obj.id }}{% else %}{{ obj.short_name }}{% endif %}{% if obj.args %}({{ obj.args }}){% endif %} + + {% for (args, return_annotation) in obj.overloads %} + {{ " " * (obj.type | length) }} {{ obj.short_name }}{% if args %}({{ args }}){% endif %} + + {% endfor %} + {% if obj.bases %} + {% if "show-inheritance" in autoapi_options %} + + Bases: {% for base in obj.bases %}{{ base|link_objs }}{% if not loop.last %}, {% endif %}{% endfor %} + {% endif %} + + + {% if "show-inheritance-diagram" in autoapi_options and obj.bases != ["object"] %} + .. autoapi-inheritance-diagram:: {{ obj.obj["full_name"] }} + :parts: 1 + {% if "private-members" in autoapi_options %} + :private-bases: + {% endif %} + + {% endif %} + {% endif %} + {% if obj.docstring %} + + {{ obj.docstring|indent(3) }} + {% endif %} + {% set this_page_children = visible_children|rejectattr("type", "in", own_page_types)|list %} + {% set visible_abstract_methods = [] %} + {% set visible_constructor_methods = [] %} + {% set visible_instance_methods = [] %} + {% set visible_special_methods = [] %} + {% set visible_static_methods = [] %} + {% set visible_properties = this_page_children|selectattr("type", "equalto", "property")|list %} + {% set visible_attributes = this_page_children|selectattr("type", "equalto", "attribute")|list %} + {% set all_visible_methods = this_page_children|selectattr("type", "equalto", "method")|list %} + {% if all_visible_methods %} + {% for element in all_visible_methods %} + {% if "abstractmethod" in element.properties %} + {% set _ = visible_abstract_methods.append(element) %} + + {% elif "staticmethod" in element.properties %} + {% set _ = visible_static_methods.append(element) %} + + {% elif "classmethod" in element.properties or element.name in ["__new__", "__init__"] %} + {% set _ = visible_constructor_methods.append(element) %} + + {% elif element.name.startswith("__") and element.name.endswith("__") and element.name not in ["__new__", "__init__"] %} + {% set _ = visible_special_methods.append(element) %} + + {% else %} + {% set _ = visible_instance_methods.append(element) %} + {% endif %} + {% endfor %} + {% endif %} + + {% if this_page_children %} + +.. py:currentmodule:: {{ obj.short_name }} +{# ------------------------- Begin tab-set definition ----------------------- #} + +Overview +-------- + +.. tab-set:: + + {% if visible_abstract_methods %} + {{ tab_item_from_objects_list(visible_abstract_methods, "Abstract methods") }} + {% endif %} + + {% if visible_constructor_methods %} + {{ tab_item_from_objects_list(visible_constructor_methods, "Constructors") }} + {% endif %} + + {% if visible_instance_methods %} + {{ tab_item_from_objects_list(visible_instance_methods, "Methods") }} + {% endif %} + + {% if visible_properties %} + {{ tab_item_from_objects_list(visible_properties, "Properties") }} + {% endif %} + + {% if visible_attributes %} + {{ tab_item_from_objects_list(visible_attributes, "Attributes") }} + {% endif %} + + {% if visible_static_methods %} + {{ tab_item_from_objects_list(visible_static_methods, "Static methods") }} + {% endif %} + + {% if visible_special_methods %} + {{ tab_item_from_objects_list(visible_special_methods, "Special methods") }} + {% endif %} + + {% endif %} +{# ---------------------- End class tabset -------------------- #} + +{# ---------------------- Begin class details -------------------- #} + +Import detail +------------- +{% set split_parts = obj.obj["full_name"].split('.') %} +{% set joined_parts = '.'.join(split_parts[:-1]) %} + + from {{ joined_parts }} import {{ obj["short_name"] }} + + {% if visible_properties %} + +Property detail +--------------- + {% for property in visible_properties %} +{{ property.render() }} + {% endfor %} + {% endif %} + + + {% if visible_attributes %} +Attribute detail +---------------- + {% for attribute in visible_attributes %} +{{ attribute.render() }} + {% endfor %} + {% endif %} + + + {% if all_visible_methods %} +Method detail +------------- + {% for method in all_visible_methods %} +{{ method.render() }} + {% endfor %} + {% endif %} + {% if is_own_page and own_page_children %} + {% set visible_attributes = own_page_children|selectattr("type", "equalto", "attribute")|list %} + {% if visible_attributes %} +Attributes +---------- + +.. autoapisummary:: + + {% for attribute in visible_attributes %} + {{ attribute.id }} + {% endfor %} + + + {% endif %} + {% set visible_exceptions = own_page_children|selectattr("type", "equalto", "exception")|list %} + {% if visible_exceptions %} +Exceptions +---------- + +.. autoapisummary:: + + {% for exception in visible_exceptions %} + {{ exception.id }} + {% endfor %} + + + {% endif %} + {% set visible_classes = own_page_children|selectattr("type", "equalto", "class")|list %} + {% if visible_classes %} +Classes +------- + +.. autoapisummary:: + + {% for klass in visible_classes %} + {{ klass.id }} + {% endfor %} + + + {% endif %} + {% set visible_methods = own_page_children|selectattr("type", "equalto", "method")|list %} + {% if visible_methods %} +Methods +------- + +.. autoapisummary:: + + {% for method in visible_methods %} + {{ method.id }} + {% endfor %} + + + {% endif %} + {% endif %} + +{# ---------------------- End class details -------------------- #} +{% endif %} \ No newline at end of file diff --git a/doc/source/_templates/autoapi/python/module.rst b/doc/source/_templates/autoapi/python/module.rst new file mode 100644 index 000000000..8665955a4 --- /dev/null +++ b/doc/source/_templates/autoapi/python/module.rst @@ -0,0 +1,252 @@ +{# ------------------------- Begin macros definition ----------------------- #} + +{% macro tab_item_from_objects_list(objects_list, title="") -%} + + .. tab-item:: {{ title }} + + .. list-table:: + :header-rows: 0 + :widths: auto + + {% for obj in objects_list %} + + {% if obj.type in own_page_types %} + * - :py:obj:`~{{ obj.id }}` + {% else %} + * - :py:obj:`~{{ obj.short_name }}` + {% endif %} + - {{ obj.summary }} + + {% endfor %} + +{%- endmacro %} + +{% macro toctree_from_objects_list(objects_list, icon="") -%} + +.. toctree:: + :titlesonly: + :maxdepth: 1 + :hidden: + + {% for obj in objects_list %} + {{ obj.short_name }}<{{ obj.include_path }}> + {% endfor %} +{%- endmacro %} + +{# --------------------------- End macros definition ----------------------- #} + +{% if not obj.display %} +:orphan: +{% endif %} + +{% if is_own_page %} + + {% if obj.name.split(".") | length == 3 %} +The ``{{ obj.name }}`` library +{{ "================" + "=" * obj.name|length }} + {% else %} + {% if obj.type == "package" %} +The ``{{ obj.short_name }}`` package +{{ "====================" + "=" * obj.short_name|length }} + {% else %} +The ``{{ obj.short_name }}.py`` module +{{ "==================" + "=" * obj.short_name|length }} + {% endif %} + {% endif %} +{% endif %} + +.. py:module:: {{ obj.name }} + +{# ---------------------- Begin module summary -------------------- #} + +Summary +------- + +{% if obj.all is not none %} +{% set visible_children = obj.children|selectattr("short_name", "in", obj.all)|list %} +{% elif obj.type is equalto("package") %} +{% set visible_children = obj.children|selectattr("display")|list %} +{% else %} +{% set visible_children = obj.children|selectattr("display")|rejectattr("imported")|list %} +{% endif %} + +{% set visible_subpackages = obj.subpackages|selectattr("display")|list %} +{% set visible_submodules = obj.submodules|selectattr("display")|list %} + +{% set visible_classes_and_interfaces = visible_children|selectattr("type", "equalto", "class")|list %} +{% set visible_functions = visible_children|selectattr("type", "equalto", "function")|list %} +{% set visible_attributes_and_constants = visible_children|selectattr("type", "equalto", "data")|list %} +{% set visible_exceptions = visible_children|selectattr("type", "equalto", "exception")|list %} + +{% set visible_classes = [] %} +{% set visible_interfaces = [] %} +{% set visible_enums = [] %} +{% for element in visible_classes_and_interfaces %} + + {# + HACK: there is not built-in "startswith" test, no "break" statement, and + no limited scope for variables inside blocks, see: + https://stackoverflow.com/questions/4870346/can-a-jinja-variables-scope-extend-beyond-in-an-inner-block + #} + {% set has_enum_base = [] %} + {% for base in element.bases %} + {% if base.startswith("enum.") %} + {% set _ = has_enum_base.append(true) %} + {% endif %} + {% endfor %} + + {% if has_enum_base %} + {% set _ = visible_enums.append(element) %} + {% elif element.name.startswith("I") and element.name[1].isupper() and not has_enum_base %} + {% set _ = visible_interfaces.append(element) %} + {% else %} + {% set _ = visible_classes.append(element) %} + {% endif %} +{% endfor %} + +{% set visible_attributes = [] %} +{% set visible_constants = [] %} +{% for element in visible_attributes_and_constants %} + {% if element.name.isupper() %} + {% set _ = visible_constants.append(element) %} + {% else %} + {% set _ = visible_attributes.append(element) %} + {% endif %} +{% endfor %} + +{% set module_objects = visible_subpackages + visible_submodules + visible_classes + visible_interfaces + visible_enums + visible_exceptions + visible_functions + visible_constants + visible_attributes %} + +{# ---------------------- End module summary -------------------- #} +{# ---------------------- Begin module tabset -------------------- #} +{% if module_objects %} + +.. py:currentmodule:: {{ obj.short_name }} +.. tab-set:: + +{% if visible_subpackages %} + {{ tab_item_from_objects_list(visible_subpackages, "Subpackages") }} +{% endif %} + +{% if visible_submodules %} + {{ tab_item_from_objects_list(visible_submodules, "Submodules") }} +{% endif %} + +{% if visible_interfaces %} + {{ tab_item_from_objects_list(visible_interfaces, "Interfaces") }} +{% endif %} + +{% if visible_classes %} + {{ tab_item_from_objects_list(visible_classes, "Classes") }} +{% endif %} + +{% if visible_enums %} + {{ tab_item_from_objects_list(visible_enums, "Enums") }} +{% endif %} + +{% if visible_exceptions %} + {{ tab_item_from_objects_list(visible_exceptions, "Exceptions") }} +{% endif %} + +{% if visible_functions %} + {{ tab_item_from_objects_list(visible_functions, "Functions") }} +{% endif %} + +{% if visible_attributes %} + {{ tab_item_from_objects_list(visible_attributes, "Attributes") }} +{% endif %} + +{% if visible_constants %} + {{ tab_item_from_objects_list(visible_constants, "Constants") }} +{% endif %} +{% endif %} + +{# ---------------------- End module tabset -------------------- #} +{# ------------------------ Begin toctree definition ----------------------- #} + +{% block subpackages %} +{% if visible_subpackages %} +{{ toctree_from_objects_list(visible_subpackages, "nf nf-md-package") }} +{% endif %} +{% endblock %} + +{% block submodules %} +{% if visible_submodules %} +{{ toctree_from_objects_list(visible_submodules, "nf nf-fa-file") }} +{% endif %} +{% endblock %} + +{% block class %} +{% if own_page_types and "class" in own_page_types %} +{% if visible_interfaces %} +{{ toctree_from_objects_list(visible_interfaces, "nf nf-cod-symbol_interface") }} +{% endif %} + +{% if visible_classes %} +{{ toctree_from_objects_list(visible_classes, "nf nf-cod-symbol_class") }} +{% endif %} + +{% if visible_enums %} +{{ toctree_from_objects_list(visible_enums, "nf nf-cod-symbol_enum") }} +{% endif %} + +{% if visible_exceptions %} +{{ toctree_from_objects_list(visible_exceptions, "nf nf-md-lightning_bolt") }} +{% endif %} +{% endif %} +{% endblock %} + +{% block functions %} +{% if own_page_types and visible_functions and "function" in own_page_types %} +{{ toctree_from_objects_list(visible_functions, "nf nf-md-function_variant") }} +{% endif %} +{% endblock %} + +{% block constants %} +{% if own_page_types and visible_constants and "constant" in own_page_types %} +{{ toctree_from_objects_list(visible_constants, "nf nf-cod-symbol_constant") }} +{% endif %} +{% endblock %} + +{# ------------------------- End toctree definition ------------------------ #} + + +{# ------------------------ Begin module description ----------------------- #} + +{% if obj.docstring %} +Description +----------- + +{{ obj.docstring }} +{% endif %} + +{# ------------------------- End module description ------------------------ #} + + +{# -------------------------- Begin module detail -------------------------- #} + +{% set module_objects_in_this_page = visible_classes + visible_interfaces + visible_enums + visible_exceptions + visible_functions + visible_constants + visible_attributes %} +{% if module_objects_in_this_page %} +{% set visible_objects_in_this_page = [] %} + +{% if own_page_types %} + {% for obj in module_objects_in_this_page %} + {% if obj.type not in own_page_types %} + {% set _ = visible_objects_in_this_page.append(obj) %} + {% endif %} + {% endfor %} +{% else %} + {% set visible_objects_in_this_page = module_objects_in_this_page %} +{% endif %} + +{% if visible_objects_in_this_page %} +Module detail +------------- + + {% for obj in visible_objects_in_this_page %} +{{ obj.render() }} + {% endfor %} + +{% endif %} +{% endif %} + +{# ---------------------- End module detail description -------------------- #} \ No newline at end of file diff --git a/doc/source/ansys_tools_path_api/path.rst b/doc/source/api/path.rst similarity index 100% rename from doc/source/ansys_tools_path_api/path.rst rename to doc/source/api/path.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index 9adeba310..bd64786a3 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -221,9 +221,7 @@ "thumbnail": "https://cheatsheets.docs.pyansys.com/pymechanical_cheat_sheet.png", "needs_download": True, }, - "ansys_sphinx_theme_autoapi": { - "project": project, - }, + "ansys_sphinx_theme_autoapi": {"project": project, "templates": "_templates/autoapi"}, "navigation_depth": 10, } diff --git a/doc/source/getting_started/installation.rst b/doc/source/getting_started/installation.rst index 5d71fa56a..f052575cc 100644 --- a/doc/source/getting_started/installation.rst +++ b/doc/source/getting_started/installation.rst @@ -75,8 +75,11 @@ This package is required to use PyMechanical. ('/usr/ansys_inc/v231/aisol/.workbench', 23.1) # Linux If you install Ansys in a directory other than the default or typical location, -you can save this directory path using the ``save_mechanical_path`` function. Then use -``get_mechanical_path`` and ``version_from_path`` functions to verify the path and version. +you can save this directory path using the +`save_mechanical_path `_ +function. Then use +`get_mechanical_path `_ +and ``version_from_path`` functions to verify the path and version. .. code:: pycon diff --git a/doc/source/user_guide_session/server-launcher.rst b/doc/source/user_guide_session/server-launcher.rst index 4ad57017d..ea625c6b0 100644 --- a/doc/source/user_guide_session/server-launcher.rst +++ b/doc/source/user_guide_session/server-launcher.rst @@ -43,8 +43,8 @@ version of Mechanical, run the following: new_path = "C:/Program Files/ANSYS Inc/v231/aisol/bin/winx64/AnsysWBU.exe" pymechanical.change_default_mechanical_path(new_path) -For more information, see the :func:`change_default_mechanical_path() ` -and :func:`find_mechanical() ` methods. +For more information, see the `change_default_mechanical_path() `_ +and `find_mechanical() `_ methods. Additionally, you can use the ``exec_file`` keyword argument to specify the location of the Mechanical executable file. From 715d7fad60c1dbaaf7998b7934e810e5c70c5519 Mon Sep 17 00:00:00 2001 From: klmcadams <58492561+klmcadams@users.noreply.github.com> Date: Fri, 14 Jun 2024 09:01:04 -0400 Subject: [PATCH 09/14] vale off for templates --- doc/source/_templates/autoapi/python/class.rst | 6 +++++- doc/source/_templates/autoapi/python/module.rst | 6 +++++- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/doc/source/_templates/autoapi/python/class.rst b/doc/source/_templates/autoapi/python/class.rst index 0a13e066a..cc1b0bb79 100644 --- a/doc/source/_templates/autoapi/python/class.rst +++ b/doc/source/_templates/autoapi/python/class.rst @@ -1,3 +1,5 @@ +.. vale off + {% if obj.display %} {# ----------------- Start macros definition for tab item ------------------#} @@ -219,4 +221,6 @@ Methods {% endif %} {# ---------------------- End class details -------------------- #} -{% endif %} \ No newline at end of file +{% endif %} + +.. vale on \ No newline at end of file diff --git a/doc/source/_templates/autoapi/python/module.rst b/doc/source/_templates/autoapi/python/module.rst index 8665955a4..c25660742 100644 --- a/doc/source/_templates/autoapi/python/module.rst +++ b/doc/source/_templates/autoapi/python/module.rst @@ -1,3 +1,5 @@ +.. vale off + {# ------------------------- Begin macros definition ----------------------- #} {% macro tab_item_from_objects_list(objects_list, title="") -%} @@ -249,4 +251,6 @@ Module detail {% endif %} {% endif %} -{# ---------------------- End module detail description -------------------- #} \ No newline at end of file +{# ---------------------- End module detail description -------------------- #} + +.. vale on \ No newline at end of file From 534127bb3438a8cc017b03269075677084229a3a Mon Sep 17 00:00:00 2001 From: klmcadams <58492561+klmcadams@users.noreply.github.com> Date: Fri, 14 Jun 2024 09:07:36 -0400 Subject: [PATCH 10/14] apply vale suggestions --- doc/source/_templates/autoapi/index.rst | 6 +++++- doc/source/architecture.rst | 8 ++++---- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/doc/source/_templates/autoapi/index.rst b/doc/source/_templates/autoapi/index.rst index b4a23cf2e..56e1b02b2 100644 --- a/doc/source/_templates/autoapi/index.rst +++ b/doc/source/_templates/autoapi/index.rst @@ -1,3 +1,5 @@ +.. vale off + API reference ============= @@ -13,4 +15,6 @@ to interact with them programmatically. See the API reference for ``ansys-tools- {% if (page.top_level_object or page.name.split('.') | length == 3) and page.display %} {{ page.name }}<{{ page.include_path }}> {% endif %} - {% endfor %} \ No newline at end of file + {% endfor %} + +.. vale on \ No newline at end of file diff --git a/doc/source/architecture.rst b/doc/source/architecture.rst index 376942b4f..4dd8fc2c1 100644 --- a/doc/source/architecture.rst +++ b/doc/source/architecture.rst @@ -21,12 +21,12 @@ solvers can be integrated into Mechanical and can take advantage of the powerful meshing, generic CAD reader, and the intuitive pre- and post- processing experience of Mechanical. -Before discussing how Mechanical's API is implemented, we discuss a software -design pattern known as the *command pattern*. This pattern can be used in many +Before discussing how Mechanical's API is implemented, the software design +pattern known as the *command pattern* is explored. This pattern can be used in many programming languages. For a general description (using the Java programming language) of the command pattern, see `Command Design Pattern `_ in the -*HowToDoInJava* newsletter. Our own brief explanation follows. +*HowToDoInJava* newsletter. Command pattern --------------- @@ -125,7 +125,7 @@ servers. Clients send requests to servers. Servers are expected return a response to the client. There are protocols [#f5]_ that describe how information moves between -computers. We begin with an explanation of remote procedure calls. +computers. The next section begins with an explanation of remote procedure calls. Remote procedure calls ---------------------- From ebfa8349687e1a404fd431e2a5eadce2a71a5661 Mon Sep 17 00:00:00 2001 From: klmcadams <58492561+klmcadams@users.noreply.github.com> Date: Fri, 14 Jun 2024 09:19:22 -0400 Subject: [PATCH 11/14] add path.html to linkcheck ignore --- doc/source/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/source/conf.py b/doc/source/conf.py index bd64786a3..4ba621480 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -302,6 +302,7 @@ "https://answers.microsoft.com/en-us/windows/forum/all/*", "https://download.ansys.com/*", "https://mechanical.docs.pyansys.com/version/stable/api/*", # Remove this after release 0.10.12 + "path.html", ] linkcheck_anchors = False From 4f63c3fbb95e84d0af712c5b17be5735f698d72f Mon Sep 17 00:00:00 2001 From: klmcadams <58492561+klmcadams@users.noreply.github.com> Date: Mon, 17 Jun 2024 11:57:54 -0400 Subject: [PATCH 12/14] use relative paths --- doc/source/getting_started/faq.rst | 4 ++-- doc/source/getting_started/installation.rst | 4 ++-- doc/source/getting_started/running_mechanical.rst | 2 +- doc/source/user_guide_embedding/configuration.rst | 4 ++-- doc/source/user_guide_embedding/index.rst | 2 +- doc/source/user_guide_embedding/logging.rst | 4 ++-- doc/source/user_guide_session/index.rst | 4 ++-- doc/source/user_guide_session/pool.rst | 8 ++++---- doc/source/user_guide_session/server-launcher.rst | 6 +++--- 9 files changed, 19 insertions(+), 19 deletions(-) diff --git a/doc/source/getting_started/faq.rst b/doc/source/getting_started/faq.rst index fe5074335..5de4aceaa 100644 --- a/doc/source/getting_started/faq.rst +++ b/doc/source/getting_started/faq.rst @@ -93,8 +93,8 @@ The way that you clear all data from Mechanical in PyMechanical depends on if Mechanical is a remote session or embedded. - If Mechanical is a remote session, use either the - `Mechanical.clear() `_ + `Mechanical.clear() <../api/ansys/mechanical/core/mechanical/Mechanical.html#Mechanical.clear>`_ method or exit and restart Mechanical. - If Mechanical is embedded, use the - `app.new() `_ + `app.new() <../api/ansys/mechanical/core/embedding/app/App.html#App.new>`_ method. diff --git a/doc/source/getting_started/installation.rst b/doc/source/getting_started/installation.rst index f052575cc..32eb795be 100644 --- a/doc/source/getting_started/installation.rst +++ b/doc/source/getting_started/installation.rst @@ -76,9 +76,9 @@ This package is required to use PyMechanical. If you install Ansys in a directory other than the default or typical location, you can save this directory path using the -`save_mechanical_path `_ +`save_mechanical_path <../api/_autosummary/ansys.tools.path.save_mechanical_path.html#ansys.tools.path.save_mechanical_path>`_ function. Then use -`get_mechanical_path `_ +`get_mechanical_path <../api/_autosummary/ansys.tools.path.get_mechanical_path.html#ansys.tools.path.get_mechanical_path>`_ and ``version_from_path`` functions to verify the path and version. .. code:: pycon diff --git a/doc/source/getting_started/running_mechanical.rst b/doc/source/getting_started/running_mechanical.rst index 36199979c..63289dc06 100644 --- a/doc/source/getting_started/running_mechanical.rst +++ b/doc/source/getting_started/running_mechanical.rst @@ -32,7 +32,7 @@ Launch Mechanical on the local machine using Python ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When Mechanical is installed locally on your machine, you can use the -`launch_mechanical() `_ +`launch_mechanical() <../api/ansys/mechanical/core/mechanical/index.html#mechanical.launch_mechanical>`_ method to launch and automatically connect to Mechanical. While this method provides the easiest and fastest way to launch Mechanical, it only works with a local Mechanical installation. diff --git a/doc/source/user_guide_embedding/configuration.rst b/doc/source/user_guide_embedding/configuration.rst index 5058c8d62..9927c56cc 100644 --- a/doc/source/user_guide_embedding/configuration.rst +++ b/doc/source/user_guide_embedding/configuration.rst @@ -5,9 +5,9 @@ Addin configuration There are some configuration options that are respected when loading an embedded instance of Mechanical into python. -The class `Configuration `_ can be +The class `Configuration <../api/ansys/mechanical/core/embedding/addins/AddinConfiguration.html#ansys.mechanical.core.embedding.addins.AddinConfiguration>`_ can be used to set up Addin configuration. This configuration can be supplied to the constructor -of the class `App `_. +of the class `App <../api/ansys/mechanical/core/embedding/app/App.html>`_. For example, to load an instance of Mechanical using the "Mechanical" configuration name and without loading any ACT Addins: diff --git a/doc/source/user_guide_embedding/index.rst b/doc/source/user_guide_embedding/index.rst index 4c32cb46b..712e5bb11 100644 --- a/doc/source/user_guide_embedding/index.rst +++ b/doc/source/user_guide_embedding/index.rst @@ -22,7 +22,7 @@ an instance of Mechanical in Python. Overview -------- -The `App `_ class provides +The `App <../api/ansys/mechanical/core/embedding/app/App.html>`_ class provides a Mechanical instance: .. code:: python diff --git a/doc/source/user_guide_embedding/logging.rst b/doc/source/user_guide_embedding/logging.rst index 8ade37b3d..b18422f6d 100644 --- a/doc/source/user_guide_embedding/logging.rst +++ b/doc/source/user_guide_embedding/logging.rst @@ -8,7 +8,7 @@ enabled by setting environment variables before starting Mechanical. With PyMech it is possible to configure logging at any time, whether it is before or after creating the embedded application, using the same Python API. -Use the `Configuration `_ class to +Use the `Configuration <../api/ansys/mechanical/core/embedding/logger/Configuration.html>`_ class to configure logging to the standard output for all warning messages and above (which are error and fatal messages). For example: @@ -22,7 +22,7 @@ For example: _ = mech.App() After the embedded application has been created, you can write messages to the same -log using the `Logger ` class like this: +log using the `Logger <../api/ansys/mechanical/core/embedding/logger/Logger.html>` class like this: .. code:: python diff --git a/doc/source/user_guide_session/index.rst b/doc/source/user_guide_session/index.rst index 0d67ec211..12ae35436 100644 --- a/doc/source/user_guide_session/index.rst +++ b/doc/source/user_guide_session/index.rst @@ -21,8 +21,8 @@ to a remote Mechanical session. Overview -------- -The `launch_mechanical() `_ method -creates an instance of the `Mechanical `_ +The `launch_mechanical() <../api/ansys/mechanical/core/mechanical/index.html#mechanical.launch_mechanical>`_ method +creates an instance of the `Mechanical <../api/ansys/mechanical/core/mechanical/Mechanical.html>`_ class in the background and sends commands to it as a service. Because errors and warnings are processed Pythonically, you can develop a script in real time without worrying about whether the script runs correctly when deployed in batch mode. diff --git a/doc/source/user_guide_session/pool.rst b/doc/source/user_guide_session/pool.rst index be4a51e6b..ded6e0f36 100644 --- a/doc/source/user_guide_session/pool.rst +++ b/doc/source/user_guide_session/pool.rst @@ -1,9 +1,9 @@ Create a pool of Mechanical servers =================================== -The `LocalMechanicalPool `_ +The `LocalMechanicalPool <../api/ansys/mechanical/core/pool/LocalMechanicalPool.html>`_ class simplifies creating and connecting to multiple servers of the -`Mechanical `_ class for batch +`Mechanical <../api/ansys/mechanical/core/mechanical/Mechanical.html>`_ class for batch processing. You can use this class for batch processing a set of input files or other batch-related processes. @@ -40,7 +40,7 @@ Run a set of input files ------------------------ You can use the pool to run a set of pre-generated input files using the -`run_batch() `_ method. +`run_batch() <../api/ansys/mechanical/core/pool/LocalMechanicalPool.html#LocalMechanicalPool.run_batch>`_ method. For example, you can run the first set of 20 verification files with this code: @@ -57,7 +57,7 @@ Run a user-defined function While the previous example uses the `run_batch()`_ method to run a set of inputs files, you can also use the -`map() `_ method to run a custom user-defined function on +`map() <../api/ansys/mechanical/core/pool/LocalMechanicalPool.html#LocalMechanicalPool.map>`_ method to run a custom user-defined function on each instance of Mechanical over a set of input files. .. code:: pycon diff --git a/doc/source/user_guide_session/server-launcher.rst b/doc/source/user_guide_session/server-launcher.rst index ea625c6b0..239ffee3c 100644 --- a/doc/source/user_guide_session/server-launcher.rst +++ b/doc/source/user_guide_session/server-launcher.rst @@ -6,7 +6,7 @@ Most of the time, PyMechanical can determine this location automatically. Howeve if you have a non-standard installation, you must provide this location. To test and set up your installation of PyMechanical, run the -`launch_mechanical() `_ +`launch_mechanical() <../api/ansys/mechanical/core/mechanical/index.html#mechanical.launch_mechanical>`_ method: .. code:: python @@ -43,8 +43,8 @@ version of Mechanical, run the following: new_path = "C:/Program Files/ANSYS Inc/v231/aisol/bin/winx64/AnsysWBU.exe" pymechanical.change_default_mechanical_path(new_path) -For more information, see the `change_default_mechanical_path() `_ -and `find_mechanical() `_ methods. +For more information, see the `change_default_mechanical_path() <../api/_autosummary/ansys.tools.path.change_default_mechanical_path.html#ansys.tools.path.change_default_mechanical_path>`_ +and `find_mechanical() <../api/_autosummary/ansys.tools.path.find_mechanical.html#ansys.tools.path.find_mechanical>`_ methods. Additionally, you can use the ``exec_file`` keyword argument to specify the location of the Mechanical executable file. From 79f8b20894fc819a82030b2a0d8dde80094dc5d9 Mon Sep 17 00:00:00 2001 From: klmcadams <58492561+klmcadams@users.noreply.github.com> Date: Mon, 17 Jun 2024 12:24:28 -0400 Subject: [PATCH 13/14] ignore local paths --- doc/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 4ba621480..1857b8929 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -301,7 +301,7 @@ "https://ansysaccount.b2clogin.com/*", "https://answers.microsoft.com/en-us/windows/forum/all/*", "https://download.ansys.com/*", - "https://mechanical.docs.pyansys.com/version/stable/api/*", # Remove this after release 0.10.12 + "../api/ansys/mechanical/core/*", # Remove this after release 0.10.12 "path.html", ] From 66cb7486ce43e2f6d929a7b8924051e0634cbadf Mon Sep 17 00:00:00 2001 From: klmcadams <58492561+klmcadams@users.noreply.github.com> Date: Mon, 17 Jun 2024 13:32:30 -0400 Subject: [PATCH 14/14] adjust linkcheck ignore url --- doc/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 1857b8929..431d3a4ae 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -301,7 +301,7 @@ "https://ansysaccount.b2clogin.com/*", "https://answers.microsoft.com/en-us/windows/forum/all/*", "https://download.ansys.com/*", - "../api/ansys/mechanical/core/*", # Remove this after release 0.10.12 + "../api/*", # Remove this after release 0.10.12 "path.html", ]