Improve launcher documentation (#2488)

* * Reorg of getting started. * Update versions * Small fixes * Fixing vale * Shortening line * Apply suggestions from code review Co-authored-by: Kathy Pippert <[email protected]> * typo * typos * first windows commands, later linux. Making those bold titled. --------- Co-authored-by: Kathy Pippert <[email protected]>
ansys · Nov 21, 2023 · cbadf18 · cbadf18
1 parent 571aae2
commit cbadf18
Show file tree

Hide file tree

Showing 18 changed files with 486 additions and 420 deletions.
diff --git a/doc/source/getting_started/contribution.rst b/doc/source/getting_started/contribution.rst
@@ -58,15 +58,15 @@ Testing MAPDL
 If you do not have MAPDL installed locally but still want to run the
 unit testing, you must set up the following environment variables.
 
-In Windows, use:
+**On Windows**
 
 .. code:: pwsh-session
 
     SET PYMAPDL_START_INSTANCE=False
     SET PYMAPDL_PORT=<MAPDL Port> (default 50052)
     SET PYMAPDL_IP=<MAPDL IP> (default 127.0.0.1)
 
-In Linux, use:
+**On Linux**
 
 .. code:: console
 

diff --git a/doc/source/getting_started/docker.rst b/doc/source/getting_started/docker.rst
@@ -85,15 +85,6 @@ container.
 To instantiate an MAPDL Docker container from an image hosted at ``ghcr.io/myuser/myrepo/mymapdldockerimage``,
 use code like in the following examples.
 
-**On Linux**
-
-.. code:: bash
-
-  ANSYSLMD_LICENSE_FILE=1055@MY_LICENSE_SERVER_IP
-  LOCAL_MAPDL_PORT=50053
-  MAPDL_DOCKER_REGISTRY_URL=ghcr.io/myuser/myrepo/mymapdldockerimage
-  docker run -e ANSYSLMD_LICENSE_FILE=$ANSYSLMD_LICENSE_FILE --restart always --name mapdl -p $LOCAL_MAPDL_PORT:50052 $MAPDL_DOCKER_REGISTRY_URL -smp > log.txt
-
 **On Windows**
 
 .. code:: pwsh-session
@@ -105,6 +96,16 @@ use code like in the following examples.
     docker run -e ANSYSLMD_LICENSE_FILE=$env:ANSYSLMD_LICENSE_FILE --restart always --name mapdl -p $env:LOCAL_MAPDL_PORT`:50052   $env:MAPDL_DOCKER_REGISTRY_URL -smp
 
 
+**On Linux**
+
+.. code:: bash
+
+  ANSYSLMD_LICENSE_FILE=1055@MY_LICENSE_SERVER_IP
+  LOCAL_MAPDL_PORT=50053
+  MAPDL_DOCKER_REGISTRY_URL=ghcr.io/myuser/myrepo/mymapdldockerimage
+  docker run -e ANSYSLMD_LICENSE_FILE=$ANSYSLMD_LICENSE_FILE --restart always --name mapdl -p $LOCAL_MAPDL_PORT:50052 $MAPDL_DOCKER_REGISTRY_URL -smp > log.txt
+
+
 The first time you instantiate the container, Docker logins into the registry and
 pulls the required image. This can take some time, depending on the size of the image.
 
@@ -162,10 +163,10 @@ number available on the host machine) with the ``-np`` switch:
 
 
 For additional command line arguments, see the *Notes* section in the
-description for the :func:`launch_mapdl() <ansys.mapdl.core.launch_mapdl>`
+description for the :func:`launch_mapdl() <ansys.mapdl.core.launcher.launch_mapdl>`
 function.
 
-You can use a script file (batch ``'.bat'`` or PowerShell ``'.ps'``)
+You can use a script file (batch ``".bat"`` or PowerShell ``".ps"``).
 to run the preceding commands all at once.
 
 Once you have launched MAPDL, you should see the following content

diff --git a/doc/source/getting_started/faq.rst b/doc/source/getting_started/faq.rst
@@ -7,11 +7,15 @@ Frequently asked questions
 How do you report issues?
 =========================
 
-To report bugs and documentation errors and to make feature requests, use the `PyMAPDL issues <pymapdl_issues_>`_ page of 
-the GitHub repository.
+If you find an issue, the first place to visit for possible solutions is the :ref:`troubleshooting section <ref_troubleshooting>`.
 
-To ask more open-ended questions or seek advice from the community, use the `PyMAPDL discussions <pymapdl_discussions_>`_ page
-of the GitHub repository.
+If you do not find a solution there, you can search for your issue within the `GitHub repository <pymapdl_repo_>`_. You can use `the search box <pymapdl_search_issues_pr_>`_ to find related issues or pull requests.
+
+To ask more open-ended questions or seek advice from the community,
+use the `PyMAPDL discussions <pymapdl_discussions_>`_ page of the GitHub repository.
+
+To report bugs and documentation errors and to make feature requests,
+use the `PyMAPDL issues <pymapdl_issues_>`_ page of the GitHub repository.
 
 
 What are the pros and cons of PyMAPDL versus Ansys ACT?
@@ -44,12 +48,15 @@ like to develop software.
 Has APDL been "deprecated" by Ansys? If so, what does that mean for PyMAPDL?
 ============================================================================
 
-APDL isn't going anywhere. In fact, whenever you call Mechanical Workbench, it's generating an input file
-(``ds.dat``) that's fed into MAPDL. However, what's changed over the past several years is where the geometry,
-meshing, and postprocessing is occurring. Geometry generation can take place within SpaceClaim or Design Modeler,
-and meshing is done using a variety of new and powerful meshers within Workbench. While these tools are
-far superior to the ones in MAPDL, their biggest limitation is that they're difficult to script
-(especially externally). As a result, there are still users who choose to generate the geometry and mesh within MAPDL.
+APDL isn't going anywhere. In fact, whenever you call Mechanical Workbench, it's
+generating an input file (``ds.dat``) that's fed into MAPDL. However, what's
+changed over the past several years is where the geometry, meshing, and
+postprocessing is occurring. Geometry generation can take place within
+SpaceClaim or Design Modeler, and meshing is done using a variety of new and
+powerful meshers within Workbench. While these tools are far superior to the
+ones in MAPDL, their biggest limitation is that they're difficult to script
+(especially externally). As a result, there are still users who choose to
+generate the geometry and mesh within MAPDL.
 
 
 What are the main reasons to use PyMAPDL over other Ansys products like Workbench?

diff --git a/doc/source/getting_started/index.rst b/doc/source/getting_started/index.rst
@@ -1,122 +1,30 @@
-===============
-Getting started
-===============
-To use PyMAPDL, you must have a local installation of Ansys. The
-version of Ansys installed dictates the interface and features
-available to you.
-
-For more information on getting a licensed copy of Ansys, visit
-`Ansys <ansys_>`_.
 
 
 .. toctree::
    :hidden:
    :maxdepth: 3
 
+   install_mapdl
+   install_pymapdl
+   launcher
    learning
+   contribution
+   faq
    versioning
-   running_mapdl
    docker
    macos
    wsl
    using_julia
-   faq
-   contribution
    make_container_link
    devcontainer_link
 
 
-.. _installation:
-
-************
-Installation
-************
-
-Python module
-~~~~~~~~~~~~~
-The ``ansys.mapdl.core`` package currently supports Python 3.8 through
-Python 3.12 on Windows, Mac OS, and Linux.
-
-Install the latest release from 
-`PyPi <pymapdl_pypi_>`_ with:
-
-.. code:: console
-
-   pip install ansys-mapdl-core
-
-Alternatively, install the latest from 
-`PyMAPDL GitHub <pymapdl_issues_>`_ via:
-
-.. code:: console
-
-   pip install git+https://github.com/ansys/pymapdl.git
-
-
-For a local *development* version, install with:
-
-.. code:: console
-
-   git clone https://github.com/ansys/pymapdl.git
-   cd pymapdl
-   pip install -e .
-
-This allows you to install the ``ansys-mapdl-core`` module
-and modify it locally and have the changes reflected in your setup
-after restarting the Python kernel.
-
-
-Offline installation
-~~~~~~~~~~~~~~~~~~~~
-If you lack an internet connection on your install machine, the recommended way
-of installing PyMAPDL is downloading the wheelhouse archive from the 
-`Releases Page <pymapdl_releases_>`_ for your corresponding
-machine architecture.
-
-Each wheelhouse archive contains all the Python wheels necessary to install
-PyMAPDL from scratch on Windows and Linux for Python 3.8 and 3.9. You can install
-this on an isolated system with a fresh Python or on a virtual environment.
-
-For example, on Linux with Python 3.8, unzip it and install it with the following:
-
-.. code:: console
-
-   unzip PyMAPDL-v0.62.dev1-wheelhouse-Linux-3.8.zip wheelhouse
-   pip install ansys-mapdl-core -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 preceding command.
-
-Consider installing using a `virtual environment <using_venv_>`_.
-
-
-Ansys software requirements
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-For the latest features, you must have a copy of Ansys 2021 R1
-installed locally. However, PyMAPDL is compatible with Ansys 17.0 and later
-on Windows and with Ansys 13.0 on Linux.
-
-.. note::
-
-    The latest versions of Ansys provide significantly better support
-    and features. Certain features are not supported on earlier
-    Ansys versions.
-
-For more information, see :ref:`install_mapdl`.
-
-Verify your installation
-~~~~~~~~~~~~~~~~~~~~~~~~
-Check that you can start MAPDL from Python by running:
-
-.. code:: pycon
-
-    >>> from ansys.mapdl.core import launch_mapdl
-    >>> mapdl = launch_mapdl()
-    >>> print(mapdl)
+===============
+Getting started
+===============
 
-    Product:             ANSYS Mechanical Enterprise
-    MAPDL Version:       RELEASE  2021 R1           BUILD 21.0
-    PyMAPDL Version:     Version: 0.58.0
+To use PyMAPDL you must follow the next three steps:
 
-If you see a response from the server, congratulations. You're ready
-to get started using MAPDL as a service. For information on the
-PyMAPDL interface, see :ref:`ref_mapdl_user_guide`.
+* :ref:`ref_using_standard_install`
+* :ref:`ref_pymapdl_installation`
+* :ref:`ref_launch_pymapdl`
diff --git a/doc/source/getting_started/install_mapdl.rst b/doc/source/getting_started/install_mapdl.rst
@@ -0,0 +1,56 @@
+
+
+.. _ref_using_standard_install: install_mapdl_
+
+.. _install_mapdl:
+
+*************
+Install MAPDL
+*************
+
+
+The PyAnsys ``ansys-mapdl-core`` package (PyMAPDL) requires either a local or
+remote instance of MAPDL to communicate with it. This section covers
+launching and interfacing with MAPDL from a local instance by
+launching it from Python.
+
+MAPDL is installed by default from the Ansys standard installer. When
+installing Ansys, verify that the **Mechanical Products** checkbox is
+selected under the **Structural Mechanics** option. While the standard
+installer options can change, see the following figure for reference.
+
+.. figure:: ../images/unified_install_2019R1.jpg
+    :width: 400pt
+
+
+If you want to avoid having to install MAPDL locally, you can use Docker.
+This is especially convenient if you are using a non-supported platform such
+as MacOS.
+For more information, see :ref:`ref_pymapdl_and_macos`.
+
+You can also download and try the `Ansys Student Version <ansys_student_version_>`_.
+A Student Version is valid during a calendar year with limited capabilities. For
+example, there is a limit on the number of nodes and elements.
+
+If you experience problems installing MAPDL on Linux, see
+:ref:`missing_dependencies_on_linux`.
+
+
+Ansys software requirements
+---------------------------
+
+For the latest features, you must have a copy of Ansys 2021 R1 or later
+installed locally. However, PyMAPDL is compatible with Ansys 17.0 and later
+on Windows and with Ansys 13.0 on Linux. However, its usage with these older
+versions is discouraged.
+
+.. note::
+
+    The latest versions of Ansys provide significantly better support
+    and features. Certain features are not supported on earlier
+    Ansys versions.
+
+For more information, see :ref:`versions_and_interfaces`.
+
+
+For information on installing PyMAPDL, see :ref:`ref_pymapdl_installation`.
diff --git a/doc/source/getting_started/install_pymapdl.rst b/doc/source/getting_started/install_pymapdl.rst
@@ -0,0 +1,84 @@
+
+
+.. _ref_pymapdl_installation:
+
+***************
+Install PyMAPDL
+***************
+
+Python module
+~~~~~~~~~~~~~
+The ``ansys.mapdl.core`` package currently supports Python 3.8 through
+Python 3.11 on Windows, Mac OS, and Linux.
+
+Install the latest release from `PyPi <pymapdl_pypi_>`_ with:
+
+.. code:: console
+
+   pip install ansys-mapdl-core
+
+Alternatively, install the latest from 
+`PyMAPDL GitHub <pymapdl_issues_>`_ with this command:
+
+.. code:: console
+
+   pip install git+https://github.com/ansys/pymapdl.git
+
+
+For a local *development* version, install with these commands:
+
+.. code:: console
+
+   git clone https://github.com/ansys/pymapdl.git
+   cd pymapdl
+   pip install -e .
+
+After installing a development version, you can modify the ``ansys-mapdl-core`` package
+locally and have the changes reflected in your setup after restarting the Python kernel.
+
+
+Offline installation
+~~~~~~~~~~~~~~~~~~~~
+If you lack an internet connection on your installation machine, the recommended way
+of installing PyMAPDL is downloading the wheelhouse archive from the 
+`Releases <pymapdl_releases_>`_ page for your corresponding
+machine architecture.
+
+Each wheelhouse archive contains all the Python wheels necessary to install
+PyMAPDL from scratch on Windows and Linux. You can install
+this on an isolated system with a fresh Python installation or on a virtual environment.
+
+For example, on Linux with Python 3.9, unzip the wheelhouse archive and install it with
+these commands:
+
+.. code:: console
+
+   unzip PyMAPDL-v0.68.dev1-wheelhouse-Linux-3.9.zip wheelhouse
+   pip install ansys-mapdl-core -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 preceding command.
+
+Consider installing using a `virtual environment <using_venv_>`_.
+
+Verify your installation
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+   To use PyMAPDL, you must have a local installation of Ansys. The
+   version of Ansys installed dictates the interface and features
+   available to you.
+
+   For more information on getting a licensed copy of Ansys, visit
+   `Ansys <ansys_>`_.
+
+
+Check that you have installed the package correctly by importing the module:
+
+.. code:: pycon
+
+    >>> from ansys.mapdl import core as pymapdl
+
+
+For information on launching PyMAPDL and connecting it
+to an MAPDL instance, see:ref:`ref_launch_pymapdl`.