doc: getting started layout

doc/source/conf.py

@@ -89,8 +89,81 @@
 
 metadata = Path(__file__).parent.parent.parent / "projects.yaml"
 
+supported_python_versions_by_metapackage_version = [
+    {
+        "version": "2023.1",
+        "python": {"lower": "3.7", "upper": "3.10"},
+        "link": "https://pypi.org/project/pyansys/2023.1.3/",
+    },
+    {
+        "version": "2023.2",
+        "python": {"lower": "3.8", "upper": "3.11"},
+        "link": "https://pypi.org/project/pyansys/2023.2.11/",
+    },
+    {
+        "version": "2024.1",
+        "python": {"lower": "3.9", "upper": "3.12"},
+        "link": "https://pypi.org/project/pyansys/2024.1.8/",
+    },
+    {
+        "version": "2024.2",
+        "python": {"lower": "3.9", "upper": "3.12"},
+        "link": "https://pypi.org/project/pyansys/2024.2.2/",
+    },
+    {
+        "version": "2025.1",
+        "python": {"lower": "3.10", "upper": "3.12"},
+        "link": "https://pypi.org/project/pyansys/2025.1.0/",
+    },
+    {
+        "version": "development",
+        "python": {"lower": "3.10", "upper": "3.12"},
+        "link": "https://github.com/ansys/pyansys",
+    },
+]
+
+
+def read_dependencies_from_pyproject():
+    pyproject = Path(__file__).parent.parent.parent / "pyproject.toml"
+    if not pyproject.exists():
+        raise ValueError(f"The file {pyproject} does not exist.")
+
+    pyproject_content = toml.loads(pyproject.read_text(encoding="utf-8"))
+    dependencies = pyproject_content["project"]["dependencies"]
+    return {pkg.split("==")[0]: pkg.split("==")[1] for pkg in dependencies}
+
+
+def read_optional_dependencies_from_pyproject():
+    pyproject = Path(__file__).parent.parent.parent / "pyproject.toml"
+    if not pyproject.exists():
+        raise ValueError(f"The file {pyproject} does not exist.")
+
+    pyproject_content = toml.loads(pyproject.read_text(encoding="utf-8"))
+    exclude_targets = ["doc"]
+    optional_dependencies = {
+        target: {pkg.split("==")[0]: pkg.split("==")[1] for pkg in deps}
+        for target, deps in pyproject_content["project"]["optional-dependencies"].items()
+        if target not in exclude_targets
+    }
+    return optional_dependencies
+
+
+jinja_globals = {
+    "VERSION": version,
+    "SUPPORTED_PYTHON_VERSIONS": ["3.10", "3.11", "3.12"],
+    "SUPPORTED_PLATFORMS": ["Windows", "macOS", "Linux"],
+}
 jinja_contexts = {
-    "project_context": {"projects": yaml.safe_load(metadata.read_text(encoding="utf-8"))}
+    "project_context": {"projects": yaml.safe_load(metadata.read_text(encoding="utf-8"))},
+    "releases": {"table_data": supported_python_versions_by_metapackage_version},
+    "dependencies": {"dependencies": read_dependencies_from_pyproject()},
+    "optional_dependencies": {"optional_dependencies": read_optional_dependencies_from_pyproject()},
+    "wheelhouse": {
+        "wheelhouse": {
+            platform: icon
+            for platform, icon in zip(["Windows", "macOS", "Linux"], ["windows", "apple", "linux"])
+        }
+    },
 }
 
 html_context = {

doc/source/getting-started.rst

@@ -0,0 +1,38 @@
+Getting started
+===============
+
+This page helps you quickly get started with PyAnsys. It lists all the
+prerequisites and guides you step by step to install the project on your
+platform.
+
+.. grid:: 1 1 3 3
+
+    .. grid-item-card:: :fa:`info-circle` About PyAnsys
+        :link: getting-started/about
+        :link-type: doc
+        :padding: 2 2 2 2
+
+        Learn more about PyAnsys and its ecosystem
+
+    .. grid-item-card:: :fa:`tasks` Prerequisites
+        :link: getting-started/prerequisites
+        :link-type: doc
+        :padding: 2 2 2 2
+
+        What you need prior installing PyAnsys
+
+    .. grid-item-card:: :fa:`download` Install
+        :link: getting-started/install
+        :link-type: doc
+        :padding: 2 2 2 2
+
+        Guidelines on how to install PyAnsys in your system
+
+.. toctree::
+    :maxdepth: 3
+    :hidden:
+
+    About<getting-started/about>
+    Prerequisites<getting-started/prerequisites>
+    Install<getting-started/install>
+

doc/source/getting-started/about.rst

@@ -0,0 +1,39 @@
+About
+#####
+
+PyAnsys is a collection of Python libraries and tools developed by `ANSYS,
+Inc.`_ It provides access to `Ansys products`_ by using a Python interface,
+enabling users to perform engineering simulations, data processing, and
+automation tasks.
+
+To ease the installation of the libraries and tools, PyAnsys provides a Python
+metapackage. This ensures compatibility between its projects.
+
+Key features of PyAnsys
+=======================
+
+PyAnsys shines in the following areas:
+
+- **Automation of workflows:** PyAnsys enables users to automate repetitive or
+  complex simulation tasks.
+
+- **Integration with the Python ecosystem:** users can leverage the Python
+  ecosystem.
+
+- **Cross-product functionality:** PyAnsys provides Python APIs for various
+  Ansys services and products. By allowing users to interact with multiple
+  products in a single environment, PyAnsys enables users to streamline their
+  workflows.
+
+The PyAnsys ecosystem
+=====================
+
+PyAnsys libraries can be classified into wrappers and tools.
+
+**Wrappers** are Python libraries that provide direct access to Ansys products.
+Communication between the product and the library is performed via `gRPC
+<grpc_>`_. Therefore, users can have the product installed remotely and connect
+to that remote instance.
+
+**Tools** are Python libraries that provide additional functionality to the
+wrappers.

doc/source/getting-started/install.rst

@@ -0,0 +1,158 @@
+Install PyAnsys
+###############
+
+.. raw:: html
+
+    <!-- Include DataTables CSS, jQuery, and JS -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.datatables.net/1.13.6/css/jquery.dataTables.min.css">
+    <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
+    <script src="https://cdn.datatables.net/1.13.6/js/jquery.dataTables.min.js"></script>
+
+Installing the PyAnsys metapackage is as simple as installing any Python
+library. However, you must have a licensed copy of `Ansys <Ansys Customer
+Portal>`_ to use it.
+
+Online installation
+===================
+
+Download and install PyAnsys from `PyPI`_:
+
+.. tab-set::
+
+    .. tab-item:: :fab:`windows` **Windows**
+
+        .. code-block:: bash
+
+            python -m pip install pyansys
+
+    .. tab-item:: :fab:`apple` **MacOS**
+
+        .. code-block:: bash
+
+            python -m pip install pyansys
+
+    .. tab-item:: :fab:`linux` **Linux**
+
+        .. code-block:: bash
+
+            python -m pip install pyansys
+
+The PyAnsys |version| metapackage includes the following projects:
+
+.. jinja:: dependencies
+
+    .. raw:: html
+
+        <!-- Initialize DataTables -->
+        <script>
+            $(document).ready(function() {
+                $('#pyansys-projects').DataTable();
+            });
+        </script>
+
+        <!-- Populate and render the table -->
+        <table id="pyansys-projects" class="display" style="width:100%">
+            <thead>
+                <tr>
+                    <th>PyAnsys project</th>
+                    <th>Version</th>
+                </tr>
+            </thead>
+            <tbody>
+                {% for project, version in dependencies.items() %}
+                <tr>
+                    <td>{{ project }}</td>
+                    <td>{{ version }}</td>
+                </tr>
+                {% endfor %}
+            </tbody>
+        </table>
+
+Additional targets
+------------------
+
+The PyAnsys metapackage contains various targets for installing additional
+libraries and tools.
+
+.. jinja:: optional_dependencies
+
+    .. tab-set::
+
+        {% for target, dependencies in optional_dependencies.items() %}
+
+        .. tab-item:: {{ target }}
+
+            Install by running:
+
+            .. code-block:: bash
+
+                python -m pip install pyansys[{{ target }}]
+
+            .. raw:: html
+
+                <!-- Initialize DataTables -->
+                <script>
+                    $(document).ready(function() {
+                        $('#target-{{ target }}').DataTable();
+                    });
+                </script>
+
+                <!-- Populate and render the table -->
+                <table id="target-{{ target }}" class="display" style="width:100%">
+                    <thead>
+                        <tr>
+                            <th>PyAnsys project</th>
+                            <th>Version</th>
+                        </tr>
+                    </thead>
+                    <tbody>
+                        {% for project, version in dependencies.items() %}
+                        <tr>
+                            <td>{{ project }}</td>
+                            <td>{{ version }}</td>
+                        </tr>
+                        {% endfor %}
+                    </tbody>
+                </table>
+
+
+
+
+         {% endfor %}
+
+
+Offline installation
+====================
+
+Start by downloading the wheelhouse artifact for your platform:
+
+.. jinja:: wheelhouse
+
+    .. csv-table::
+       :header-rows: 1
+       :widths: 16, 28, 28, 28
+
+       :fas:`laptop` Platform,
+       {%- for python in SUPPORTED_PYTHON_VERSIONS -%}
+       :fab:`python` Python {{ python }}
+       {%- if not loop.last -%},{%- endif -%}
+       {% endfor %}
+       {% for platform, icon in wheelhouse.items() -%}
+       :fab:`{{ icon }}` {{ platform }},
+       {%- for python in SUPPORTED_PYTHON_VERSIONS -%}
+       `Download wheelhouse <https://github.com/ansys/pyansys/releases/download/v{{ VERSION }}/pyansys-v{{ VERSION }}-all-wheelhouse-{{ platform }}-{{ python }}.zip>`__
+       {%- if not loop.last -%},{%- endif -%}
+       {% endfor %}
+       {% endfor %}
+
+Next, decompress the artifacts:
+
+.. code-block:: bash
+
+    unzip <path/to/wheelhouse.zip> wheelhouse
+
+Finally, install the PyAnsys metapackage using previously downloaded wheelhouse:
+
+.. code-block:: bash
+
+    python -m pip install pyansys -f wheelhouse --no-index --upgrade --ignore-installed