diff --git a/doc/source/_static/custom.css b/doc/source/_static/custom.css index a778107dd98..f2239c4e7f3 100644 --- a/doc/source/_static/custom.css +++ b/doc/source/_static/custom.css @@ -14,3 +14,4 @@ .sd-bg-text-fluent{color: Black} .sd-bg-cfx{background-color: LightSeaGreen} .sd-bg-text-cfx{color: Black} +.sd-hide-link-text{height: 0} diff --git a/doc/source/conf.py b/doc/source/conf.py index 8732a03339e..3293be97668 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -19,6 +19,7 @@ # Make sphinx_utilities modules importable sys.path.append(os.path.join(os.path.dirname(__file__), "../sphinx_utilities")) +from version_filtering import get_tutorial_version_requirements # Manage errors pyvista.set_error_output_file("errors.txt") @@ -59,13 +60,12 @@ ) server_version = server_instance.version server.shutdown_all_session_servers() -print(f"DPF version: {server_version}") -print(f"DPF install: {server_instance.ansys_path}") +print("".rjust(40, '*')) +print(f"Doc built for DPF server version {server_version} at:\n{server_instance.ansys_path}") +print("".rjust(40, '*')) # Build ignore pattern ignored_pattern = r"(ignore" -header_flag = "\"\"\"" -note_flag = r".. note::" for example in sorted(glob(r"../../examples/**/*.py")): minimum_version_str = get_example_required_minimum_dpf_version(example) if float(server_version) - float(minimum_version_str) < -0.05: @@ -76,6 +76,15 @@ ignored_pattern += "|06-distributed_stress_averaging.py" ignored_pattern += r")" +exclude_patterns = [] +for tutorial_file in glob(str(Path("user_guide")/"tutorials"/"**"/"*.rst")): + if Path(tutorial_file).name == "index.rst": + continue + minimum_version_str = get_tutorial_version_requirements(tutorial_file) + if float(server_version) - float(minimum_version_str) < -0.05: + print(f"Tutorial {Path(tutorial_file).name} skipped as it requires DPF {minimum_version_str}.") + exclude_patterns.append(tutorial_file.replace("\\", "/")) + # Autoapi ignore pattern autoapi_ignore_list = [ "*/log.py", @@ -118,7 +127,6 @@ "sphinx_design", "sphinx_jinja", 'sphinx_reredirects', - "ansys_sphinx_theme.extension.autoapi", "jupyter_sphinx", ] @@ -163,7 +171,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ["links_and_refs.rst"] +exclude_patterns.extend(["links_and_refs.rst"]) # make rst_epilog a variable, so you can add other epilog parts to it rst_epilog = "" @@ -411,3 +419,5 @@ def setup(app): BUILD_EXAMPLES = True if os.environ.get("BUILD_EXAMPLES", "true") == "true" else False if BUILD_EXAMPLES: extensions.extend(["sphinx_gallery.gen_gallery"]) + +print(f"{extensions=}") diff --git a/doc/source/user_guide/tutorials/custom_operators_and_plugins/custom_operators.rst b/doc/source/user_guide/tutorials/custom_operators_and_plugins/custom_operators.rst index 6e82a779ecf..0836c0afa4c 100644 --- a/doc/source/user_guide/tutorials/custom_operators_and_plugins/custom_operators.rst +++ b/doc/source/user_guide/tutorials/custom_operators_and_plugins/custom_operators.rst @@ -4,9 +4,14 @@ Custom operators ================ +.. note:: + + This tutorial requires DPF 11.0 or above. + This tutorial shows the basics of creating a custom operator in Python and loading it ont a server for use. -.. note: +.. note:: + You can create custom operators in CPython using PyDPF-Core for use with DPF in Ansys 2023 R1 and later. It first presents how to :ref:`create a custom DPF operator` @@ -19,7 +24,8 @@ The next step is to :ref:`load the plugin on the server`. -.. note: +.. note:: + In this tutorial the DPF client API used is PyDPF-Core but, once recorded on the server, you can call the operators of the plugin using any of the DPF client APIs (C++, CPython, IronPython), as you would any other operator. diff --git a/doc/source/user_guide/tutorials/custom_operators_and_plugins/index.rst b/doc/source/user_guide/tutorials/custom_operators_and_plugins/index.rst index 04f58ecbff9..728596e31bb 100644 --- a/doc/source/user_guide/tutorials/custom_operators_and_plugins/index.rst +++ b/doc/source/user_guide/tutorials/custom_operators_and_plugins/index.rst @@ -23,7 +23,8 @@ With support for custom operators, PyDPF-Core becomes a development tool offerin The only prerequisite for creating custom operators is to be familiar with native operators. For more information, see :ref:`ref_user_guide_operators`. -.. note: +.. note:: + You can create custom operators in CPython using PyDPF-Core for use with DPF in Ansys 2023 R1 and later. The following tutorials demonstrate how to develop such plugins using PyDPF-Core (CPython based) and how to use them. @@ -36,44 +37,48 @@ For comprehensive examples on writing operator plugins, see :ref:`python_operato :margin: 2 .. grid-item-card:: Create a DPF plugin with a single operator - :link: tutorials_custom_operators_and_plugins_custom_operator - :link-type: ref - :text-align: center + :link: tutorials_custom_operators_and_plugins_custom_operator + :link-type: ref + :text-align: center + :class-header: sd-bg-light sd-text-dark + :class-footer: sd-bg-light sd-text-dark - This tutorial shows how to create, load, and use a custom plugin containing a single custom operator. + This tutorial shows how to create, load, and use a custom plugin containing a single custom operator. - .. grid-item-card:: Create a DPF plugin with multiple operators - :text-align: center - :class-card: sd-bg-light - :class-header: sd-bg-light + +++ + Requires DPF 11.0 or above - Coming soon - ^^^ + .. grid-item-card:: Create a DPF plugin with multiple operators + :text-align: center + :class-header: sd-bg-light sd-text-dark + :class-footer: sd-bg-light sd-text-dark + This tutorial shows how to create, load, and use a custom plugin with multiple operators or with complex routines. - This tutorial shows how to create, load, and use a custom plugin with multiple operators or with complex routines. + +++ + Coming soon .. grid-item-card:: Create a custom DPF plugin with third-party dependencies using Python - :text-align: center - :class-card: sd-bg-light - :class-header: sd-bg-light + :text-align: center + :class-header: sd-bg-light sd-text-dark + :class-footer: sd-bg-light sd-text-dark - Coming soon - ^^^ + This tutorial shows how to create a Python plug-in package with third-party dependencies. - This tutorial shows how to create a Python plug-in package with third-party dependencies. + +++ + Coming soon .. grid-item-card:: Update PyDPF-Core in the DPF installation :text-align: center :class-card: sd-bg-light - :class-header: sd-bg-light - - Coming soon - ^^^ - + :class-header: sd-bg-light sd-text-dark + :class-footer: sd-bg-light sd-text-dark This tutorial shows how to update PyDPF-Core in your DPF installation. + +++ + Coming soon + .. toctree:: :maxdepth: 2 :hidden: diff --git a/doc/source/user_guide/tutorials/index.rst b/doc/source/user_guide/tutorials/index.rst index 1456e688d23..f14a6a1b6b7 100644 --- a/doc/source/user_guide/tutorials/index.rst +++ b/doc/source/user_guide/tutorials/index.rst @@ -25,33 +25,34 @@ of our package background so you can understand how to work with it. :margin: 2 .. grid-item-card:: PyDPF-Core data structures - :link: ref_tutorials_data_structures - :link-type: ref - :text-align: center + :link: ref_tutorials_data_structures + :link-type: ref + :text-align: center - Learn the different data structures used by DPF when handling data + Learn the different data structures used by DPF when handling data .. grid-item-card:: PyDPF-Core language - :text-align: center - :class-card: sd-bg-light - :class-header: sd-bg-light + :text-align: center + :class-card: sd-bg-light + :class-header: sd-bg-light sd-text-dark + :class-footer: sd-bg-light sd-text-dark - Coming soon - ^^^ + Check an overview on how to use PyDPF-Core API. + Learn the different ways to interact with data by using PyDPF-Core + objects and methods. - Check an overview on how to use PyDPF-Core API. - Learn the different ways to interact with data by using PyDPF-Core - objects and methods. + +++ + Coming soon .. grid-item-card:: Post-processing data basics - :link: ref_tutorials_processing_basics - :link-type: ref - :text-align: center + :link: ref_tutorials_processing_basics + :link-type: ref + :text-align: center - Learn the basics on a post-processing procedure - using PyDPf-Core based on its usual main steps. The goal is to - transform simulation data into output data that can be used to - visualize and analyze simulation results. + Learn the basics on a post-processing procedure + using PyDPf-Core based on its usual main steps. The goal is to + transform simulation data into output data that can be used to + visualize and analyze simulation results. :fa:`book-open-reader` Common topics ************************************ @@ -62,104 +63,110 @@ of our package background so you can understand how to work with it. :margin: 2 .. grid-item-card:: Import Data on DPF - :link: ref_tutorials_import_data - :link-type: ref - :text-align: center + :link: ref_tutorials_import_data + :link-type: ref + :text-align: center - Understand how to represent data in DPF: either from manual input either form result files. + Understand how to represent data in DPF: either from manual input either form result files. .. grid-item-card:: Mesh exploration - :link: ref_tutorials_mesh - :link-type: ref - :text-align: center + :link: ref_tutorials_mesh + :link-type: ref + :text-align: center - Learn how to explore a mesh in DPF. + Learn how to explore a mesh in DPF. .. grid-item-card:: Manipulate data with operators and workflows - :text-align: center - :class-card: sd-bg-light - :class-header: sd-bg-light + :text-align: center + :class-card: sd-bg-light + :class-header: sd-bg-light sd-text-dark + :class-footer: sd-bg-light sd-text-dark - Coming soon - ^^^ + Learn how to use operators to process your data and build workflows. - Learn how to use operators to process your data and build workflows. + +++ + Coming soon .. grid-item-card:: Export data from DPF - :text-align: center - :class-card: sd-bg-light - :class-header: sd-bg-light + :text-align: center + :class-card: sd-bg-light + :class-header: sd-bg-light sd-text-dark + :class-footer: sd-bg-light sd-text-dark - Coming soon - ^^^ + Discover the best ways to export data from your manipulations with PyDPF-Core. - Discover the best ways to export data from your manipulations with PyDPF-Core. + +++ + Coming soon .. grid-item-card:: Plot - :link: ref_tutorials_plot - :link-type: ref - :text-align: center + :link: ref_tutorials_plot + :link-type: ref + :text-align: center - Explore the different approaches to visualise the data in plots. + Explore the different approaches to visualise the data in plots. .. grid-item-card:: Animate - :link: ref_tutorials_animate - :link-type: ref - :text-align: center + :link: ref_tutorials_animate + :link-type: ref + :text-align: center - Explore the different approaches to visualise the data in an animation. + Explore the different approaches to visualise the data in an animation. .. grid-item-card:: Mathematical operations - :link: ref_tutorials_mathematics - :link-type: ref - :text-align: center + :link: ref_tutorials_mathematics + :link-type: ref + :text-align: center - Learn how to do mathematical operations using PyDPF-Core and data structures + Learn how to do mathematical operations using PyDPF-Core and data structures .. grid-item-card:: Manipulating physics data - :text-align: center - :class-card: sd-bg-light - :class-header: sd-bg-light + :text-align: center + :class-card: sd-bg-light + :class-header: sd-bg-light sd-text-dark + :class-footer: sd-bg-light sd-text-dark - Coming soon - ^^^ + Learn how to manipulate the physics data associate to a + data storage structure. (Unit, homogeneity ...) - Learn how to manipulate the physics data associate to a - data storage structure. (Unit, homogeneity ...) + +++ + Coming soon .. grid-item-card:: Custom Python operator and plugin - :link: ref_tutorials_custom_operators_and_plugins - :link-type: ref - :text-align: center + :link: ref_tutorials_custom_operators_and_plugins + :link-type: ref + :text-align: center - Discover how to enhance DPF capabilities by creating your own operators and plugins. + Discover how to enhance DPF capabilities by creating your own operators and plugins. .. grid-item-card:: Post-process distributed files - :text-align: center - :class-card: sd-bg-light - :class-header: sd-bg-light + :text-align: center + :class-card: sd-bg-light + :class-header: sd-bg-light sd-text-dark + :class-footer: sd-bg-light sd-text-dark - Coming soon - ^^^ + Learn how to use PyDPF-Core with distributed files. - Learn how to use PyDPF-Core with distributed files. + +++ + Coming soon .. grid-item-card:: DPF server - :text-align: center - :class-card: sd-bg-light - :class-header: sd-bg-light + :text-align: center + :class-card: sd-bg-light + :class-header: sd-bg-light sd-text-dark + :class-footer: sd-bg-light sd-text-dark - Coming soon - ^^^ + Understand how to manipulate DPF client-server architecture - Understand how to manipulate DPF client-server architecture + +++ + Coming soon .. grid-item-card:: Licensing - :text-align: center - :class-card: sd-bg-light - :class-header: sd-bg-light + :text-align: center + :class-card: sd-bg-light + :class-header: sd-bg-light sd-text-dark + :class-footer: sd-bg-light sd-text-dark - Coming soon - ^^^ + Understand how to access the Entry and Premium licensing capabilities - Understand how to access the Entry and Premium licensing capabilities \ No newline at end of file + +++ + Coming soon \ No newline at end of file diff --git a/doc/sphinx_utilities/version_filtering.py b/doc/sphinx_utilities/version_filtering.py new file mode 100644 index 00000000000..d3609e84e34 --- /dev/null +++ b/doc/sphinx_utilities/version_filtering.py @@ -0,0 +1,25 @@ +# +from pathlib import Path + + +def get_tutorial_version_requirements(tutorial_path: str) -> str: + note_flag = r".. note::" + version_flag = "This tutorial requires DPF" + previous_line_is_note = False + minimum_version = "0.0" + tutorial_path = Path(tutorial_path) + skip_empty_line = False + with tutorial_path.open(mode="rt", encoding="utf-8") as tutorial_file: + for line in tutorial_file: + if (version_flag in line) and previous_line_is_note: + minimum_version = line.strip(version_flag).split()[0] + break + if note_flag in line: + previous_line_is_note = True + skip_empty_line = True + else: + if skip_empty_line: + skip_empty_line = False + else: + previous_line_is_note = False + return minimum_version diff --git a/src/ansys/dpf/core/examples/examples.py b/src/ansys/dpf/core/examples/examples.py index 53ae359f823..6569b0541d2 100644 --- a/src/ansys/dpf/core/examples/examples.py +++ b/src/ansys/dpf/core/examples/examples.py @@ -29,7 +29,7 @@ from ansys.dpf.core.core import upload_file_in_tmp_folder -def get_example_required_minimum_dpf_version(file: os.PathLike) -> str: +def get_example_required_minimum_dpf_version(file: str) -> str: """Return the minimal DPF server version required to run the example, as declared in a note. Parameters