New tutorials section (#1876)

Co-authored-by: Paul Profizi <[email protected]>
Co-authored-by: Revathy Venugopal <[email protected]>
Co-authored-by: PProfizi <[email protected]>
Co-authored-by: JennaPaikowsky <[email protected]>
Co-authored-by: moe-ad <[email protected]>
Co-authored-by: Camille Bellot <[email protected]>
Co-authored-by: Muhammed Adedigba <[email protected]>
Co-authored-by: Jorge Martínez <[email protected]>

Author: 7 people

doc/source/_static/custom.css

@@ -2,3 +2,16 @@
 .wy-table-responsive table td, .wy-table-responsive table th {
     white-space: normal;
 }
+/* Check https://www.w3schools.com/cssref/css_colors.php for colors */
+/* Ansys gold for MAPDL with black text*/
+.sd-bg-mapdl{background-color: #FFB71B}
+.sd-bg-text-mapdl{color: Black}
+/* Ansys orange accent color for Fluent with black text*/
+.sd-bg-lsdyna{background-color: #FB471F}
+.sd-bg-text-lsdyna{color: Black}
+/* Ansys blue accent color #00629F for Fluent with black text*/
+.sd-bg-fluent{background-color: #0081D0}
+.sd-bg-text-fluent{color: Black}
+.sd-bg-cfx{background-color: LightSeaGreen}
+.sd-bg-text-cfx{color: Black}
+.sd-hide-link-text{height: 0}

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,6 +127,7 @@
     "sphinx_design",
     "sphinx_jinja",
     'sphinx_reredirects',
+    "jupyter_sphinx",
 ]
 
 redirects = {
@@ -137,6 +147,7 @@
 
 autosummary_generate = False
 
+autodoc_mock_imports = ["ansys.dpf.core.examples.python_plugins"]
 
 # Add any paths that contain templates here, relative to this directory.
 # templates_path = ['_templates']
@@ -160,7 +171,14 @@
 # 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 = []
+exclude_patterns.extend(["links_and_refs.rst"])
+
+# make rst_epilog a variable, so you can add other epilog parts to it
+rst_epilog = ""
+
+# Read links and targets from file
+with open("links_and_refs.rst") as f:
+    rst_epilog += f.read()
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None
@@ -358,6 +376,20 @@
 # A list of files that should not be packed into the epub file.
 epub_exclude_files = ["search.html"]
 
+# Define custom docutils roles for solver badges
+from sphinx_design.badges_buttons import BadgeRole
+
+def setup(app):
+    badge_roles = {
+        "bdg-mapdl": "mapdl",
+        "bdg-cfx": "cfx",
+        "bdg-fluent": "fluent",
+        "bdg-lsdyna": "lsdyna"
+    }
+
+    for role_name, color in badge_roles.items():
+        app.add_role(name=role_name, role=BadgeRole(color=color))
+
 # Common content for every RST file such us links
 rst_epilog = ""
 links_filepath = Path(__file__).parent.absolute() / "links.rst"
@@ -387,3 +419,5 @@
 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=}")

doc/source/getting_started/contribute/developer.rst

@@ -1,27 +1,14 @@
+.. _contributing_as_a_developer:
+
 Contributing as a developer
 ###########################
 
-.. grid:: 1 2 3 3
-    :padding: 2 2 2 2
-
-    .. grid-item-card:: :fa:`download` Clone the repository
-        :link: clone-the-repository
-        :link-type: ref
-
-        Download your own copy in your local machine.
-
-    .. grid-item-card:: :fa:`download` Install for developers
-        :link: install-for-developers
-        :link-type: ref
-
-        Install the project in editable mode.
-
-    .. grid-item-card:: :fa:`vial-circle-check` Run the tests
-        :link: run-tests
-        :link-type: ref
-
-        Verify your changes by testing the project.
+You can contribute to PyDPF-Core by fixing bugs, adding new features, and improving the codebase.
+To do so, you must set up the repository on your local machine by following the steps below:
 
+- :ref:`clone-the-repository`
+- :ref:`install-for-developers`
+- :ref:`run-tests`
 
 .. _clone-the-repository:
 
@@ -44,9 +31,13 @@ Installing PyDPF-Core in development mode allows you to perform changes to the c
 and see the changes reflected in your environment without having to reinstall
 the library every time you make a change.
 
+To do so, follow the steps below.
+
 Virtual environment
 -------------------
 
+First, set up a new virtual environment.
+
 Start by navigating to the project's root directory by running:
 
 .. code-block:: bash
@@ -117,7 +108,9 @@ Install Tox
 Once the project is installed, you can install `Tox`_. This is a cross-platform
 automation tool. The main advantage of Tox is that it eases routine tasks like project
 testing, documentation generation, and wheel building in separate and isolated Python
-virtual environments. To install Tox, run:
+virtual environments.
+
+To install Tox, run:
 
 .. code-block:: text
 
@@ -154,10 +147,14 @@ Run the tests
 =============
 
 Once you have made your changes, you can run the tests to verify that your
-modifications did not break the project. PyDPF-Core tests are organized into groups and require additional steps
+modifications did not break the project.
+
+PyDPF-Core tests are organized into groups and require additional steps
 during execution to ensure tests run as expected without errors, therefore, PyDPF-Core tox configuration
 supports different markers to account for this. These markers are associated with a
-dedicated `Tox`_ environment. To also allow flexibity required during development, different DPF Server installation
+dedicated `Tox`_ environment.
+
+To also allow flexibility required during development, a specific DPF Server installation
 can also be used as explained in the subsections that follow.
 
 Unified DPF Server installation or specific DPF Server installation using ANSYS_DPF_PATH environment variable

doc/source/getting_started/contribute/documentarian.rst

@@ -1,37 +1,49 @@
-Contributing as a documentarian
-###############################
+.. _contributing_documentation:
+
+Contributing to the documentation
+#################################
+
+.. note::
+
+    Overall guidance on contributing to the documentation of a PyAnsys repository appears in
+    `Documenting`_ in the *PyAnsys Developer's Guide*.
+
+    You must also follow the `Documentation style`_ guide to
+    ensure that all the documentation looks the same across the project.
+
+To contribute on the documentation you must start by setting up the PyDPF-Core repository
+by following the steps in :ref:`contributing_as_a_developer` section.
+
+In this page you can check how to :
 
 .. grid:: 1 2 3 3
     :padding: 2 2 2 2
 
-    .. grid-item-card:: :fa:`pencil` Write documentation
-        :link: write-documentation
+    .. grid-item-card:: :fa:`th` Structure the documentation
+        :link: structure-documentation
         :link-type: ref
 
-        Explain how to get started, use, and contribute to the project.
+        How the documentation is structured and where to locate files.
 
-    .. grid-item-card:: :fa:`laptop-code` Add a new example
-        :link: write-examples
+    .. grid-item-card:: :fa:`pencil` Write documentation
+        :link: write-product-use-documentation
         :link-type: ref
 
-        Showcase the capabilities of PyDPF-Core by adding a new example. 
+        Explains and showcases the use of PyDPF-Core.
 
     .. grid-item-card:: :fa:`book` Build the documentation
         :link: build-documentation
         :link-type: ref
 
         Render the documentation to see your changes reflected.
 
-.. _write-documentation:
+.. _structure-documentation:
 
-Write documentation
-===================
+Structure the documentation
+===========================
 
 The documentation generator used in PyDPF-Core is `Sphinx`_. Most of the documents
-are written in `reStructuredText`_. Some parts of the documentation, like the
-:ref:`examples <Examples>`, use a mix of `reStructuredText`_ and Python, thanks to `Sphinx-Gallery`_.
-If you are interested in writing examples, see the :ref:`writing examples <write-examples>` 
-section.
+are written in `reStructuredText`_.
 
 The documentation is located in the ``doc/source`` directory. The landing page
 is declared in the ``doc/source/index.rst`` file. The rest of the files contain
@@ -42,7 +54,7 @@ files.
 The layout of the ``doc/source`` directory is reflected in the slug of the
 online documentation. For example, the
 ``doc/source/getting_started/contribute/documentarian.rst`` renders as
-``https://dpf.docs.pyansys.com/getting_started/contribute/documentarian.html``. 
+``https://dpf.docs.pyansys.com/getting_started/contribute/documentarian.html``.
 
 Thus, if you create a new file, it important to follow these rules:
 
@@ -70,38 +82,75 @@ A table of contents can be declared using a directive like this:
 The path to the file is relative to the directory where the table of contents
 is declared.
 
-.. _write-examples:
+.. _write-product-use-documentation:
 
-Write a new example
+Write documentation
 ===================
 
-The :ref:`examples <Examples>` section of the documentation showcases different
-capabilities of PyDPF-Core. Each example (grouped into folders of related examples)
-is a standalone Python script. Despite being ``*.py`` files, they are written in a mix
-of `reStructuredText`_ and Python. This is possible thanks to the `Sphinx-Gallery`_
-Sphinx extension.
+Our documentation tries to follow a structure principle that respects four different functions of the documentation.
+Each of them fulfills a different need for people working with our tool at different times, in different circumstances.
+
+Here is an overview of how our documentation is organized to help you know where you should include your contributions.
+Each section has their own guidelines that must be followed when creating new content.
+To check these specific guidelines click on the correspondent card below.
+
+.. grid:: 1 1 2 2
+    :gutter: 2
+    :padding: 2
+    :margin: 2
 
-Documentarians writing new examples are encouraged to familiarize themselves with
-`structuring Python scripts for Sphinx-Gallery <https://sphinx-gallery.github.io/stable/syntax.html>`_.
-Once the ``.py`` file for a new example is properly set up, Sphinx-Gallery automatically
-generates `Sphinx`_ `reStructuredText`_ files from it. The rendering of the resulting reST will provide
-users with ``.ipynb`` (Jupyter notebook) and ``.py`` files of each example, which users can download.
+    .. grid-item-card:: **TUTORIALS**
+       :link: ref_guidelines_tutorials
+       :link-type: ref
+       :class-title: sd-text-center sd-bg-light
+       :class-header: sd-text-center
 
-Finally, here are some tips for writing examples:
+       Learning oriented
+       ^^^^^^^^^^^^^^^^^
 
-- Start the example with an explanation of the main topic. Try to use as many relevant
-  keywords as possible in this section to optimize for Search Engine Optimization.
+       **Function:**  Teach how to get started and use PYDPF-core step by step
 
-- Include an explanation with each code cell. The explanations should
-  be included before, not after, the corresponding code.
+       Teach how to perform a task and showcase the underlying concepts,
+       providing detailed explanations at each stage. A tutorial is centered around a given feature.
 
-- The examples are built with the documentation. As part of the build process,
-  screenshots of rendered graphics are inserted in the document. You do not need
-  to include the screenshots yourself.
+    .. grid-item-card:: **EXAMPLES**
+       :link: ref_guidelines_examples
+       :link-type: ref
+       :class-title: sd-text-center sd-bg-light
+       :class-header: sd-text-center
 
-- When creating a new folder where more than one related example will be included, ensure
-  a ``README.txt`` file is also included. This file should contain reST to be used as the header
-  for the index page corresponding to the subsection for these examples in the generated documentation.
+       Use-cases oriented
+       ^^^^^^^^^^^^^^^^^^
+
+       **Function:**  Show how to solve specifics key problems
+
+       Showcase a specific key problem or use-case with a complete PyDPF script. They are more advanced than
+       tutorials as they present end-to-end engineering workflows and assume basic knowledge of PyDPF-Core.
+
+    .. grid-item-card:: **CONCEPTS**
+       :class-title: sd-text-center sd-bg-light
+       :class-header: sd-text-center
+
+       Understanding oriented
+       ^^^^^^^^^^^^^^^^^^^^^^
+
+       **Function:**  Provide useful theoretical explanations for PyDPF-Core
+
+       Discuss and explain key DPF principles and concepts, for the reader to understand the spirit of the underlying tool.
+
+
+    .. grid-item-card:: **API REFERENCE**
+       :class-title: sd-text-center sd-bg-light
+       :class-header: sd-text-center
+
+       Informing oriented
+       ^^^^^^^^^^^^^^^^^^
+
+       **Function:** Describe PyDPF-Core APIs
+
+       Provides technical reference on how PyDPF-Core works and how to use it but assume basic
+       understanding of key DPF concepts. It is generated automatically along the documentation and
+       is based on the source code.
 
 .. _build-documentation:
 
@@ -162,3 +211,10 @@ are modified.
     .. code-block:: text
 
         python -m tox -e doc-html -x testenv:doc-html.setenv+="BUILD_API=false" -x testenv:doc-html.setenv+="BUILD_EXAMPLES=false"
+
+.. toctree::
+    :hidden:
+    :maxdepth: 3
+
+    guidelines_tutorials
+    guidelines_examples