Fix the documentation

README.rst

@@ -1,5 +1,5 @@
-Ansys Math
-==========
+AnsysMath
+=========
 
 |pyansys| |pypi| |PyPIact| |GH-CI| |codecov| |zenodo| |MIT| |black|
 
@@ -30,36 +30,9 @@ Ansys Math
   :alt: black
 
 
-Overview
---------
+AnsysMath is a Python repository holding Ansys mathematical libraries.
 
-Ansys Math is a Python repository holding Ansys mathematical libraries.
 
+.. include:: ref_getting_started_
 
-Code Style
-----------
-Code style can be checked by running:
-
-.. code-block:: text
-
-    tox -e style
-
-Previous command will run `pre-commit <https://pre-commit.com/>`_ for checking code quality.
-
-
-Documentation
--------------
-Documentation can be rendered by running:
-
-.. code-block:: text
-
-  tox -e doc
-
-The resultant HTML files can be inspected using your favorite web browser:
-
-.. code-block:: text
-
-  <browser> .tox/doc_out_html/index.html
-
-Previous will open the rendered documentation in the desired browser.
 

doc/source/api_ref/index.rst

@@ -0,0 +1,15 @@
+
+.. _ref_index_api:
+
+API reference
+=============
+
+This page gives an overview of the API of the public AnsysMath classes,
+functions, and attributes.
+
+
+
+.. toctree::
+   :maxdepth: 1
+
+   math

doc/source/api_ref/math.rst

@@ -0,0 +1,12 @@
+.. _ref_math:
+
+.. currentmodule:: ansys.math.core
+
+.. autosummary::
+   :toctree: _autosummary
+
+   math.Math
+   math.ApdlMathObj
+   math.AnsVec
+   math.AnsMat
+   math.AnsSolver

doc/source/conf.py

@@ -1,6 +1,7 @@
 """Sphinx documentation configuration file."""
 from datetime import datetime
 import os
+import warnings
 
 from ansys_sphinx_theme import ansys_favicon, get_version_match, pyansys_logo_black
 import numpy as np
@@ -28,7 +29,14 @@
 pyvista.BUILDING_GALLERY = True
 amath.BUILDING_GALLERY = True
 
-# Project information
+# suppress annoying matplotlib bug
+warnings.filterwarnings(
+    "ignore",
+    category=UserWarning,
+    message="Matplotlib is currently using agg, which is a non-GUI backend, so cannot show the figure.",
+)
+
+# -- Project information -----------------------------------------------------
 project = "ansys-math-core"
 copyright = f"(c) {datetime.now().year} ANSYS, Inc. All rights reserved"
 author = "ANSYS, Inc."
@@ -37,7 +45,7 @@
 # Select desired logo, theme, and declare the html title
 html_logo = pyansys_logo_black
 html_theme = "ansys_sphinx_theme"
-html_short_title = html_title = "Ansys Math"
+html_short_title = html_title = "AnsysMath"
 
 cname = os.getenv("DOCUMENTATION_CNAME", "<DEFAULT_CNAME>")
 """The canonical name of the webpage hosting the documentation."""
@@ -48,6 +56,8 @@
     "github_url": "https://github.com/pyansys/ansys-math",
     "show_prev_next": False,
     "show_breadcrumbs": True,
+    "collapse_navigation": True,
+    "use_edit_page_button": True,
     "additional_breadcrumbs": [
         ("PyAnsys", "https://docs.pyansys.com/"),
     ],
@@ -65,6 +75,14 @@
     "navbar_end": ["version-switcher", "theme-switcher", "navbar-icon-links"],
 }
 
+html_context = {
+    "display_github": True,  # Integrate GitHub
+    "github_user": "pyansys",
+    "github_repo": "pymapdl",
+    "github_version": "main",
+    "doc_path": "doc/source",
+}
+
 # Sphinx extensions
 extensions = [
     "jupyter_sphinx",
@@ -114,6 +132,8 @@
     # "grpc": ("https://grpc.github.io/grpc/python/", None),
 }
 
+suppress_warnings = ["label.*"]
+# supress_warnings = ["ref.option"]
 # numpydoc configuration
 numpydoc_show_class_members = False
 numpydoc_xref_param_type = True

doc/source/contributing/index.rst

@@ -0,0 +1,80 @@
+.. _ref_contributing:
+
+Contributing
+============
+
+Overall guidance on contributing to a PyAnsys library appears in the
+`Contributing <dev_guide_contributing_>`_ topic
+in the *PyAnsys Developer's Guide*. Ensure that you are thoroughly familiar
+with it and all `Coding style <dev_guide_coding_style_>`_ before attempting to
+contribute to PyMAPDL.
+
+The following contribution information is specific to PyMAPDL.
+
+Cloning the AnsysMath repository
+--------------------------------
+
+Run this code to clone and install the latest version of PyMAPDL in development mode::
+
+    git clone https://github.com/pyansys/ansys-math
+    cd ansys-math
+    python -m pip install --upgrade pip
+    pip install -e .
+
+Posting issues
+--------------
+
+Use the `AnsysMath Issues <amath_issues_>`_ page to submit questions,
+report bugs, and request new features. When possible,use these issue
+templates:
+
+* Bug report template
+* Feature request template
+
+If your issue does not fit into one of these categories, create your own issue.
+
+To reach the project support team, email `pyansys.support@ansys.com <pyansys_support_>`_.
+
+
+Building documentation
+----------------------
+
+To build the AnsysMath documentation locally, in the root directory of the repository, run::
+
+    pip install .[doc]
+    .\doc\make.bat html 
+
+Documentation for the latest stable release of AnsysMath is hosted at
+`AnsysMath Documentation <amath_docs_>`_.
+
+Documentation for the latest development version, which tracks the
+``main`` branch, is hosted at 
+`Development AnsysMath Documentation <amath_dev_docs_>`_.
+This version is automatically kept up to date via GitHub actions.
+
+
+Code style
+----------
+
+AnsysMath follows PEP8 standard as outlined in the `PyAnsys Development Guide
+<dev_guide_pyansys_>`_ and implements style checking using
+`pre-commit <precommit_>`_.
+
+To ensure your code meets minimum code styling standards, run::
+
+  pip install pre-commit
+  pre-commit run --all-files
+
+You can also install this as a pre-commit hook by running::
+
+  pre-commit install
+
+This way, it's not possible for you to push code that fails the style checks. For example::
+
+  $ pre-commit install
+  $ git commit -am "added my cool feature"
+  black....................................................................Passed
+  isort....................................................................Passed
+  flake8...................................................................Passed
+  codespell................................................................Passed
+

doc/source/getting_started/index.rst

@@ -1,19 +1,19 @@
-===============
+.. _ref_getting_started:
+
 Getting started
 ===============
-To use Ansys Math, you must have a local installation of Ansys.
+To use AnsysMath, you must have a local installation of Ansys.
 
 For more information on getting a licensed copy of Ansys, visit
 `Ansys <ansys_>`_ .
 
 
 
-************
 Installation
-************
+------------
 
-Python module
-~~~~~~~~~~~~~
+For users
+~~~~~~~~~
 The ``ansys.math.core`` package currently supports Python 3.7 through
 Python 3.10 on Windows, Mac OS, and Linux.
 
@@ -22,13 +22,16 @@ Python 3.10 on Windows, Mac OS, and Linux.
    pip install ansys-math-core
 
 Alternatively, install the latest from 
-`Ansys Math GitHub <ansys_math_github_>`_ via:
+`AnsysMath GitHub <amath_github_>`_ via:
 
 .. code::
 
    pip install git+https://github.com/pyansys/ansys-math.git
 
 
+
+For developers
+~~~~~~~~~~~~~~~
 For a local *development* version, install with:
 
 .. code::
@@ -43,17 +46,28 @@ after restarting the Python kernel.
 
 
 Verify your installation
-~~~~~~~~~~~~~~~~~~~~~~~~
-Check that you can start Ansys Math from Python by running:
+------------------------
+
+Check that you can start AnsysMath from Python by running:
 
 .. code:: python
 
     import ansys.math.core.math as amath
 
-    # Start Ansys Math
+    # Start AnsysMath
     mm = amath.Math()
     print(mm)
 
 
 If you see a response from the server, congratulations. You're ready
-to get started using Ansys Math as a service.
+to get started using AnsysMath as a service.
+
+Ansys software requirements
+---------------------------
+
+You must have a copy of Ansys 2021 R1 or later installed locally.
+
+.. note::
+
+    The latest versions of Ansys provide significantly better support
+    and features. AnsysMath is not supported on earlier Ansys versions.