Adapting main README and docs (#46)

* WIP: Readme first version

* Issue with badge

* Removing navbar items for now

* Generate weelhouse for all targets

* README improvements

* Missing link

* Solving vale issues

* Improvements to README - extra targets

* Update README.rst

Co-authored-by: Kathy Pippert <[email protected]>

* Update README.rst

Co-authored-by: Kathy Pippert <[email protected]>

* Update README.rst

Co-authored-by: Kathy Pippert <[email protected]>

* Update README.rst

Co-authored-by: Kathy Pippert <[email protected]>

* Update README.rst

Co-authored-by: Kathy Pippert <[email protected]>

* Solving issues with links

* Alphabetical reordering

Co-authored-by: Kathy Pippert <[email protected]>

Author: RobPasMue

.github/workflows/ci-build.yml

@@ -110,21 +110,21 @@ jobs:
           echo "::set-output name=PYANSYS_VERSION::$(python -c "from pyansys import __version__; print(__version__)")"
         id: version
 
-      - name: Generate wheelhouse
+      - name: Generate wheelhouse (for all targets)
         run: |
           pip install wheel
-          pip wheel . -w wheelhouse
+          pip wheel .[all] -w wheelhouse
 
       - name: Zip wheelhouse
         uses: vimtor/action-zip@v1
         with:
           files: wheelhouse
-          dest: ${{ env.PACKAGE_NAME }}-v${{ steps.version.outputs.PYANSYS_VERSION }}-wheelhouse-${{ runner.os }}-${{ matrix.python-version }}-core.zip
+          dest: ${{ env.PACKAGE_NAME }}-v${{ steps.version.outputs.PYANSYS_VERSION }}-wheelhouse-${{ runner.os }}-${{ matrix.python-version }}.zip
 
       - name: Upload Wheelhouse
         uses: actions/upload-artifact@v3
         with:
-          name: ${{ env.PACKAGE_NAME }}-v${{ steps.version.outputs.PYANSYS_VERSION }}-wheelhouse-${{ runner.os }}-${{ matrix.python-version }}-core
+          name: ${{ env.PACKAGE_NAME }}-v${{ steps.version.outputs.PYANSYS_VERSION }}-wheelhouse-${{ runner.os }}-${{ matrix.python-version }}
           path: '*.zip'
           retention-days: 7
 

README.rst

@@ -1,153 +1,162 @@
-PyAnsys
-=======
-Welcome to the PyAnsys project. While this project originated as a single ``pyansys`` package,
-it is now a collection of many Python packages for using Ansys products through Python:
-
-- `PyAEDT <https://aedtdocs.pyansys.com/>`__ : Pythonic interface to AEDT (Ansys Electronic Desktop)
-- `PyDPF-Core <https://dpfdocs.pyansys.com/>`__ : Pythonic interface to DPF (Data Processing Framework) for building more advanced and customized workflows
-- `PyDPF-Post <https://postdocs.pyansys.com/>`__ : Pythonic interface to DPF's postprocessing toolbox for manipulating and transforming simulation data
-- `PyMAPDL <https://mapdldocs.pyansys.com/>`__ : Pythonic interface to MAPDL.
-- `PyMAPDL Reader <https://readerdocs.pyansys.com/>`__: Pythonic interface to read legacy MAPDL result files (MAPDL 14.5 and later)
-- `PyFluent <https://fluentdocs.pyansys.com/>`__ : Pythonic interface to Ansys Fluent
-- `PyPIM <https://pypim.docs.pyansys.com/>`__: Pythonic interface to communicate with the PIM (Product Instance Management) API
-- `Granta MI BoM Analytics <https://grantami.docs.pyansys.com/>`__: Pythonic interface to Granta MI BoM Analytics services
+PyAnsys metapackage
+===================
+|pyansys| |python| |pypi| |GH-CI| |MIT| |black|
+
+.. |pyansys| image:: https://img.shields.io/badge/Py-Ansys-ffc107.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAABDklEQVQ4jWNgoDfg5mD8vE7q/3bpVyskbW0sMRUwofHD7Dh5OBkZGBgW7/3W2tZpa2tLQEOyOzeEsfumlK2tbVpaGj4N6jIs1lpsDAwMJ278sveMY2BgCA0NFRISwqkhyQ1q/Nyd3zg4OBgYGNjZ2ePi4rB5loGBhZnhxTLJ/9ulv26Q4uVk1NXV/f///////69du4Zdg78lx//t0v+3S88rFISInD59GqIH2esIJ8G9O2/XVwhjzpw5EAam1xkkBJn/bJX+v1365hxxuCAfH9+3b9/+////48cPuNehNsS7cDEzMTAwMMzb+Q2u4dOnT2vWrMHu9ZtzxP9vl/69RVpCkBlZ3N7enoDXBwEAAA+YYitOilMVAAAAAElFTkSuQmCC
+   :target: https://docs.pyansys.com/
+   :alt: PyAnsys
+
+.. |python| image:: https://img.shields.io/pypi/pyversions/pyansys?logo=pypi
+   :target: https://pypi.org/project/pyansys/
+   :alt: Python
+
+.. |pypi| image:: https://img.shields.io/pypi/v/pyansys.svg?logo=python&logoColor=white
+   :target: https://pypi.org/project/pyansys/
+   :alt: PyPI
+
+.. |GH-CI| image:: https://github.com/pyansys/pyansys/actions/workflows/ci-build.yml/badge.svg
+   :target: https://github.com/pyansys/pyansys/actions/workflows/ci-build.yml
+   :alt: GH-CI
+
+.. |MIT| image:: https://img.shields.io/badge/License-MIT-yellow.svg
+   :target: https://opensource.org/licenses/MIT
+   :alt: MIT
+
+.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=flat
+   :target: https://github.com/psf/black
+   :alt: Black
+
+Welcome to the PyAnsys metapackage repository. This project originated as a single ``pyansys`` package,
+which provides support to Ansys product releases. Compatibility of these packages amongst themselves
+and with the Ansys product release they are linked to is ensured.
+
+At this moment, this package ensures the compatibility between the following PyAnsys packages:
+
+- `PyAEDT <https://aedt.docs.pyansys.com/>`_ : Pythonic interface to AEDT (Ansys Electronic Desktop)
+- `PyDPF-Core <https://dpf.docs.pyansys.com/>`_ : Pythonic interface to DPF (Data Processing Framework) for building more advanced and customized workflows
+- `PyDPF-Post <https://post.docs.pyansys.com/>`_ : Pythonic interface to DPF's postprocessing toolbox for manipulating and transforming simulation data
+- `PyFluent <https://fluent.docs.pyansys.com/>`_ : Pythonic interface to Ansys Fluent
+- `PyFluent-Parametric <https://fluentparametric.docs.pyansys.com/>`_ : Pythonic interface to Ansys Fluent parametric workflows
+- `PyFluent-Visualization <https://fluentvisualization.docs.pyansys.com/>`_ : Pythonic interface to visualize Ansys Fluent simulations using Python
+- `PyMAPDL <https://mapdl.docs.pyansys.com/>`_ : Pythonic interface to MAPDL.
+- `PyMAPDL Reader <https://reader.docs.pyansys.com/>`_: Pythonic interface to read legacy MAPDL result files (MAPDL 14.5 and later)
+- `PyPIM <https://pypim.docs.pyansys.com/>`_: Pythonic interface to communicate with the PIM (Product Instance Management) API
+- `Granta MI BoM Analytics <https://grantami.docs.pyansys.com/>`_: Pythonic interface to Granta MI BoM Analytics services
 - `Shared Components <https://shared.docs.pyansys.com/>`_: Shared software components to enable package interoperability and minimize maintenance
 
 Much effort is underway to continue expanding and developing packages in the
 `PyAnsys GitHub <https://github.com/pyansys/>`__ account. On the ``Issues`` page
 for each package, you can post issues and request new features. You can also email
 questions to `PyAnsys Support <mailto:[email protected]>`_.
 
-Package installation
---------------------
-You must install the applicable packages for an Ansys product on your local machine.
-While there are multiple ways to install a Python package, using `pip
-<https://pypi.org/project/pip/>`_, the package installer for Python, is recommended.
-For your convenience, this section provides ``pip`` commands for downloading
-and installing the most recent PyAnsys packages and links to comprehensive resources.
-
-PyAEDT
-~~~~~~
-
-.. code::
-
-   pip install pyaedt
-
-
-- `PyAEDT Documentation <https://aedtdocs.pyansys.com/>`_
-- `PyAEDT PyPI <https://pypi.org/project/pyaedt/>`_
-- `PyAEDT GitHub <https://github.com/pyansys/PyAEDT/>`_
-
-
-PyDPF-Core
-~~~~~~~~~~
-
-.. code::
+By default, the PyAnsys package installs these core modules:
 
-   pip install ansys-dpf-core
+- `PyAEDT`_
+- `PyDPF-Core`_
+- `PyDPF-Post`_
+- `PyFluent`_
+- `PyMAPDL`_
+- `PyPIM`_
+- `Granta MI BoM Analytics`_
+- `Shared Components`_
 
+However, the ``pyansys`` package also contains certain extra targets, which can be installed upon request:
 
-- `DPF-Core Documentation <https://dpfdocs.pyansys.com/>`__
-- `DPF-Core PyPI <https://pypi.org/project/ansys-dpf-core/>`__
-- `DPF-Core GitHub <https://github.com/pyansys/pydpf-core>`__
+- **mapdl-all**: this target installs the core packages and `PyMAPDL Reader`_.
+- **fluent-all**: this target installs the core packages and `PyFluent-Parametric`_ and `PyFluent-Visualization`_.
+- **all**: this target install all extra ``pyansys`` packages.
 
+Package installation
+--------------------
 
-PyDPF-Post
-~~~~~~~~~~
-
-.. code::
-
-   pip install ansys-dpf-post
-
-
-- `DPF-Post Documentation <https://postdocs.pyansys.com/>`_
-- `DPF-Post PyPI <https://pypi.org/project/ansys-dpf-post/>`_
-- `DPF-Post GitHub <https://github.com/pyansys/pydpf-post>`_
-
-
-PyMAPDL
-~~~~~~~
-
-.. code::
+Two installation modes are provided: user and offline.
 
-   pip install ansys-mapdl-core
+User mode installation
+^^^^^^^^^^^^^^^^^^^^^^
 
+Before installing ``pyansys`` in user mode, ensure that you have the latest
+version of `pip <https://pypi.org/project/pip/>`_ with:
 
-- `PyMAPDL Documentation <https://mapdldocs.pyansys.com/>`_
-- `PyMAPDL PyPI <https://pypi.org/project/ansys-mapdl-core/>`_
-- `PyMAPDL GitHub <https://github.com/pyansys/pymapdl/>`_
+.. code:: bash
+   
+    python -m pip install -U pip
 
+Then, install ``pyansys`` with:
 
-PyMAPDL Reader
-~~~~~~~~~~~~~~
+.. code:: bash
 
-.. code::
+   python -m pip install pyansys
 
-   pip install ansys-mapdl-reader
+If you are interested in **installing an extra target** such as ``fluent-all``:
 
+.. code:: bash
 
-- `Legacy PyMAPDL Reader Documentation <https://readerdocs.pyansys.com/>`_
-- `Legacy PyMAPDL Reader PyPI <https://pypi.org/project/ansys-mapdl-reader/>`_
-- `Legacy PyMAPDL Reader GitHub <https://github.com/pyansys/pymapdl-reader>`_
+   python -m pip install pyansys[fluent-all]
 
+If you are interested in **installing a specific version** such as ``2023.1.0``:
 
-PyFluent
-~~~~~~~~
+.. code:: bash
 
-.. code::
+   python -m pip install pyansys==2023.1.0
 
-   pip install ansys-fluent-core
+Offline mode installation
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
-- `PyFluent Documentation <https://fluentdocs.pyansys.com/>`_
-- `PyFluent PyPI <https://pypi.org/project/ansys-fluent-core>`_
-- `PyFluent GitHub <https://github.com/pyansys/pyfluent/>`_
+If you lack an internet connection on your installation machine, the recommended way of installing
+the ``pyansys`` metapackage is downloading the wheelhouse archive from the
+`Releases Page <https://github.com/pyansys/pyansys/releases>`_ for your corresponding machine architecture.
 
+Each wheelhouse archive contains all the Python wheels necessary to install ``pyansys`` metapackage from
+scratch on Windows, Linux, and MacOS from Python 3.7 to 3.10. You can install this on an isolated system with
+a fresh Python installation or on a virtual environment.
 
-PyPIM
-~~~~~
+For example, on Linux with Python 3.7, unzip the wheelhouse archive and install it with the following:
 
-.. code::
+.. code:: bash
 
-   pip install ansys-platform-instancemanagement
+    unzip pyansys-v2023.1.dev0-wheelhouse-Linux-3.7-core.zip wheelhouse
+    pip install pyansys -f wheelhouse --no-index --upgrade --ignore-installed
 
+If you're on Windows with Python 3.9, unzip to a wheelhouse directory and install using the same command as above.
 
-- `PyPIM Documentation <https://pypim.docs.pyansys.com/>`_
-- `PyPIM PyPI <https://pypi.org/project/ansys-platform-instancemanagement/>`_
-- `PyPIM GitHub <https://github.com/pyansys/pypim/>`_
+Consider installing using a `virtual environment <https://docs.python.org/3/library/venv.html>`_.
 
+Versioning system
+-----------------
 
-Granta MI BoM Analytics
-~~~~~~~~~~~~~~~~~~~~~~~
+The ``pyansys`` metapackage follows a semantic-like versioning system, though it has been adapted to the
+Ansys product release mechanism. In that sense, the following kind of versioning system is followed:
 
-.. code::
+.. code:: bash
 
-   pip install ansys-grantami-bomanalytics
+   XXXX.Y.ZZ
 
+Where:
 
-- `Granta MI BoM Analytics Documentation <https://grantami.docs.pyansys.com/>`_
-- `Granta MI BoM Analytics PyPI <https://pypi.org/project/ansys-grantami-bomanalytics/>`_
-- `Granta MI BoM Analytics GitHub <https://github.com/pyansys/grantami-bomanalytics/>`_
+- ``XXXX`` is the Ansys product release year (for example, 2022)
+- ``Y`` is the Ansys product release within the same year (for example, 1, which relates to R1)
+- ``ZZ`` is the patched versions to the ``pyansys`` metapackage, if any.
 
+Consequently, the first ``pyansys`` metapackage compatible with the 2024 R2 release would be:
 
-Shared components
-~~~~~~~~~~~~~~~~~
-The PyAnsys project publishes and consumes shared software components that enable
-interoperability between PyAnsys packages and minimize maintenance. For more
-information, see the `Shared Components documentation <https://shared.docs.pyansys.com/>`_.
+.. code:: bash
 
+   2024.2.0
 
-The OpenAPI Common library is a shared component. Here is the command for downloading
-and installing the most recent package and links to its comprehensive resources:
+And any subsequent patched version of that package would be:
 
-.. code::
+.. code:: bash
 
-   pip install ansys-openapi-common
+   2024.2.1
+   2024.2.2
+   2024.2.3
+   ...
 
+You can request for a specific version install when pip installing your package:
 
-- `OpenAPI Common Documentation <https://openapi.docs.pyansys.com/index.html/>`_
-- `OpenAPI Common PyPI <https://pypi.org/project/ansys-openapi-common/>`_
-- `OpenAPI Common GitHub <https://github.com/pyansys/openapi-common/>`_
+.. code:: bash
 
+   python -m pip install pyansys==2024.2.0
 
 License and acknowledgments
 ---------------------------

doc/source/index.rst

@@ -2,16 +2,6 @@
    :hidden:
    :maxdepth: 3
 
-   PyAEDT <https://aedtdocs.pyansys.com/>
-   PyDPF-Core <https://dpfdocs.pyansys.com/>
-   PyDPF-Post <https://postdocs.pyansys.com/>
-   PyMAPDL <https://mapdldocs.pyansys.com/>
-   PyMAPDL Reader <https://readerdocs.pyansys.com/>
-   PyFluent <https://fluentdocs.pyansys.com/>
-   PyPIM <https://pypim.docs.pyansys.com/>
-   Granta MI BoM Analytics <https://grantami.docs.pyansys.com/>
-   Shared Components <https://shared.docs.pyansys.com/>
-
 ..
    Simply reuse the README.rst to avoid duplication
 

doc/styles/Vocab/ANSYS/accept.txt

@@ -13,4 +13,5 @@ PyDPF-Post
 PyDPF
 PyFluent
 PyPIM
-Granta MI BoM Analytics
+Granta MI BoM Analytics
+metapackage