From 976b2886893ef5f73958fdc545de93f3e8f99648 Mon Sep 17 00:00:00 2001 From: Kerry McAdams <58492561+klmcadams@users.noreply.github.com> Date: Fri, 24 Jan 2025 09:17:23 -0500 Subject: [PATCH] docs: Clarify support guidelines (#1061) Co-authored-by: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com> --- README.rst | 26 ++++--- doc/changelog.d/1061.documentation.md | 1 + doc/source/conf.py | 17 +++-- doc/source/kil/index.rst | 92 ++++++++++++----------- doc/source/user_guide_scripting/index.rst | 22 +++--- 5 files changed, 91 insertions(+), 67 deletions(-) create mode 100644 doc/changelog.d/1061.documentation.md diff --git a/README.rst b/README.rst index e30aebcab..4122930b2 100644 --- a/README.rst +++ b/README.rst @@ -124,8 +124,23 @@ on Windows and Linux for version 2023 R2 and later. Here is an example: app.update_globals(globals()) project_dir = DataModel.Project.ProjectDirectory -Documentation and issues ------------------------- +How to report issues +-------------------- + +If you encounter any issues or limitations with PyMechanical that hinder your work, please create +an issue or discussion so our team can address them promptly: + +* `PyMechanical Issues `_: Report bugs and request new features. +* `PyMechanical Discussions `_: Post questions, share ideas, and get community feedback. + +For issues pertaining to `Mechanical scripting `_, +please make a post on the `Developer Portal `_. + +If you have general questions about PyAnsys or are unsure which repository to place an issue in, +email `pyansys.core@ansys.com `_. + +Documentation resources +----------------------- Documentation for the latest stable release of PyMechanical is hosted at `PyMechanical documentation `_. @@ -139,13 +154,6 @@ You can also `view `_ page, -you can create issues to report bugs and request new features. On the `PyMechanical Discussions -`_ page or the `Discussions `_ -page on the Ansys Developer portal, you can post questions, share ideas, and get community feedback. - -To reach the project support team, email `pyansys.core@ansys.com `_. - Testing and development ----------------------- diff --git a/doc/changelog.d/1061.documentation.md b/doc/changelog.d/1061.documentation.md new file mode 100644 index 000000000..60a9ce79c --- /dev/null +++ b/doc/changelog.d/1061.documentation.md @@ -0,0 +1 @@ +Clarify support guidelines \ No newline at end of file diff --git a/doc/source/conf.py b/doc/source/conf.py index 3d403f2f8..5b4b20155 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -21,6 +21,9 @@ # necessary when building the sphinx gallery pymechanical.BUILDING_GALLERY = True +# Whether or not to build the cheatsheet +BUILD_CHEATSHEET = True + # suppress annoying matplotlib bug warnings.filterwarnings( "ignore", @@ -57,10 +60,12 @@ "sphinx_autodoc_typehints", "sphinx_copybutton", "sphinx_design", - "sphinx_gallery.gen_gallery", "sphinxemoji.sphinxemoji", ] +if pymechanical.BUILDING_GALLERY: + extensions.append("sphinx_gallery.gen_gallery") + # Intersphinx mapping intersphinx_mapping = { "python": ("https://docs.python.org/3", None), @@ -207,14 +212,16 @@ "icon": "fa fa-comment fa-fw", }, ], - "cheatsheet": { - "file": "cheatsheet/cheat_sheet.qmd", - "title": "PyMechanical cheat sheet", - }, "ansys_sphinx_theme_autoapi": {"project": project, "templates": "_templates/autoapi"}, "navigation_depth": 10, } +if BUILD_CHEATSHEET: + html_theme_options["cheatsheet"] = { + "file": "cheatsheet/cheat_sheet.qmd", + "title": "PyMechanical cheat sheet", + } + # -- Options for HTMLHelp output --------------------------------------------- # Output file base name for HTML help builder. diff --git a/doc/source/kil/index.rst b/doc/source/kil/index.rst index ec8360c78..7e6ec3802 100644 --- a/doc/source/kil/index.rst +++ b/doc/source/kil/index.rst @@ -1,43 +1,49 @@ -.. _ref_known_issues_and_limitation: - -Known issues and limitations -============================ - -Note the following known issues and limitations. Some features may not be fully compatible across different versions of **Mechanical** and **PyMechanical**. -Ansys recommends that you always use the latest version of both to achieve the best results. - -.. - This toctree must be a top-level index to get it to show up in - pydata_sphinx_theme. - -.. toctree:: - :maxdepth: 2 - :hidden: - - - mechanical - pymechanical - -.. grid:: 2 - :gutter: 2 2 3 4 - - .. grid-item-card:: :fas:`fa-solid fa-gears` Mechanical - :link: mechanical - :link-type: doc - - Known issues and limitations of Standalone Mechanical - - .. grid-item-card:: :fab:`fa-brands fa-python` PyMechanical - :link: pymechanical - :link-type: doc - - Known issues and limitations of PyMechanical - -Support -======= - -If you encounter any issues or limitations that hinder your work, please contact our support team immediately. -We are committed to providing timely assistance to ensure your projects run smoothly. - -- Mechanical : `Discussion forum `_ -- PyMechanical : Create issue in github or contact `pyansys team `_ \ No newline at end of file +.. _ref_known_issues_and_limitation: + +Known issues and limitations +============================ + +Note the following known issues and limitations. Some features may not be fully compatible across different versions of **Mechanical** and **PyMechanical**. +Ansys recommends that you always use the latest version of both to achieve the best results. + +.. + This toctree must be a top-level index to get it to show up in + pydata_sphinx_theme. + +.. toctree:: + :maxdepth: 2 + :hidden: + + + mechanical + pymechanical + +.. grid:: 2 + :gutter: 2 2 3 4 + + .. grid-item-card:: :fas:`fa-solid fa-gears` Mechanical + :link: mechanical + :link-type: doc + + Known issues and limitations of Standalone Mechanical + + .. grid-item-card:: :fab:`fa-brands fa-python` PyMechanical + :link: pymechanical + :link-type: doc + + Known issues and limitations of PyMechanical + +Support +======= + +If you encounter any issues or limitations with PyMechanical that hinder your work, please create +an issue or discussion so our team can address them promptly: + +* `PyMechanical Issues `_: Report bugs and request new features. +* `PyMechanical Discussions `_: Post questions, share ideas, and get community feedback. + +For issues pertaining to `Mechanical scripting `_, +please make a post on the `Ansys Developer Forum for Mechanical `_. + +If you have general questions about PyAnsys or are unsure which repository to place an issue in, +email `pyansys.core@ansys.com `_. diff --git a/doc/source/user_guide_scripting/index.rst b/doc/source/user_guide_scripting/index.rst index 808d51e95..aa03add0f 100644 --- a/doc/source/user_guide_scripting/index.rst +++ b/doc/source/user_guide_scripting/index.rst @@ -23,11 +23,19 @@ You could already perform scripting of Mechanical with Python from inside Mechanical. PyMechanical leverages the same APIs but allows you to run your automation from outside Mechanical. -.. note:: +For comprehensive information on these APIs, refer to the following documentation: - For comprehensive information on these APIs, see the `Scripting in Mechanical Guide`_ in the - Ansys Help portal, the `Mechanical scripting interface APIs`_ in the Developer Portal, or the - `Mechanical API Documentation`_. +PyMechanical documentation: + +* `Mechanical API Documentation`_ - Lists Mechanical APIs that can be used with PyMechanical. + +Developer portal: + +* `Mechanical scripting interface APIs`_ - Contains the same information as the `Mechanical API Documentation`_ but is located on the developer portal. + +ACT API Reference Guide: + +* `ACT API Reference Guide`_ - Provides descriptions of the objects, methods, and properties for all namespaces. Recording --------- @@ -89,9 +97,3 @@ When running scripts inside of Mechanical, you can access the APIs via these ent You also have access to several types and namespaces that are included in the scripting scope but are not available from those entry points. - -Additional resources --------------------- - -The `ACT API Reference Guide`_ -provides descriptions of the objects, methods, and properties for all namespaces.