Fix the documentation

.github/workflows/ci_cd.yml

@@ -287,6 +287,7 @@ jobs:
           python-version: ${{ env.MAIN_PYTHON_VERSION }}
           checkout: false
           skip-install: true
+          sphinxopts: -j auto
 
 
   doc-deploy-dev:

.gitignore

@@ -36,13 +36,13 @@ var/
 # autogenerated docs
 _autosummary
 
-
 # Testing
 .coverage
 .tox/
 *,cover
 test-output.xml
 .pytest_cache/
+tests/__pycache__
 
 \#*
 .\#*

.pre-commit-config.yaml

@@ -2,14 +2,22 @@ repos:
 
 
 - repo: https://github.com/psf/black
-  rev: 22.10.0
+  rev: 22.12.0
   hooks:
   - id: black
     args:
-      - --line-length=120
+      - --line-length=100
+
+- repo: https://github.com/adamchainz/blacken-docs
+  rev: v1.12.1
+  hooks:
+  - id: blacken-docs
+    additional_dependencies: [black==22.12.0]
+    args:
+      - --line-length=100
 
 - repo: https://github.com/pycqa/isort
-  rev: 5.10.1
+  rev: 5.11.4
   hooks:
   - id: isort
 
@@ -27,6 +35,15 @@ repos:
     args: ["--toml", "pyproject.toml"]
     additional_dependencies: ["tomli"]
 
+# To be activated after quick dev cycles
+#
+# - repo: https://github.com/pycqa/pydocstyle
+#   rev: 6.1.1
+#   hooks:
+#   - id: pydocstyle
+#     additional_dependencies: [toml]
+#     exclude: "tests/"
+
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v4.4.0
   hooks:
@@ -38,11 +55,3 @@ repos:
   rev: 0.19.2
   hooks:
     - id: check-github-workflows 
-
-# - repo: https://github.com/pycqa/pydocstyle
-#   rev: 6.1.1
-#   hooks:
-#   - id: pydocstyle
-#     files: ^pyoptics/
-#     args: ["--ignore=D205,D100,D213"]
-#     additional_dependencies: [toml]

README.rst

@@ -1,5 +1,5 @@
-Ansys Math
-==========
+PyAnsys Math
+============
 
 |pyansys| |pypi| |PyPIact| |GH-CI| |codecov| |zenodo| |MIT| |black|
 
@@ -30,36 +30,73 @@ Ansys Math
   :alt: black
 
 
-Overview
---------
+PyAnsys Math is a Python repository holding Ansys mathematical libraries.
+To use them, you must have a local installation of Ansys Mechanical APDL.
 
-Ansys Math is a Python repository holding Ansys mathematical libraries.
+For more information on getting a licensed copy of Ansys Mechanical APDL, visit
+the `Ansys web site <ansys_>` .
 
 
-Code Style
-----------
-Code style can be checked by running:
 
-.. code-block:: text
+Installation
+------------
 
-    tox -e style
+For users
+~~~~~~~~~
+The ``ansys.math.core`` package currently supports Python 3.7 through
+Python 3.10 on Windows, Mac OS, and Linux.
 
-Previous command will run `pre-commit <https://pre-commit.com/>`_ for checking code quality.
+.. code::
 
+   pip install ansys-math-core
 
-Documentation
--------------
-Documentation can be rendered by running:
+Alternatively, install the latest from 
+`PyAnsys Math GitHub <pymath_github_>`_ via:
 
-.. code-block:: text
+.. code::
 
-  tox -e doc
+   pip install git+https://github.com/pyansys/ansys-math.git
 
-The resultant HTML files can be inspected using your favorite web browser:
 
-.. code-block:: text
 
-  <browser> .tox/doc_out_html/index.html
+For developers
+~~~~~~~~~~~~~~
+For a local *development* version, install with:
 
-Previous will open the rendered documentation in the desired browser.
+.. code::
 
+   git clone https://github.com/pyansys/ansys-math.git
+   cd ansys-math
+   pip install -e .
+
+This allows you to install and edit the ``ansys-math-core`` module locally.
+The changes that you make are reflected in your setup
+after restarting the Python kernel.
+
+
+Verify your installation
+------------------------
+
+Check that you can start PyAnsys Math from Python by running this code:
+
+.. code:: python
+
+    import ansys.math.core.math as pymath
+
+    # Start PyAnsys Math.
+    mm = pymath.AnsMath()
+    print(mm)
+
+
+If you see a response from the server, congratulations. You're ready
+to start using PyAnsys Math 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. PyAnsys Math is not supported on Ansys versions earlier than 2021 R1.

doc/source/api_ref/index.rst

@@ -0,0 +1,11 @@
+
+.. _ref_index_api:
+
+API reference
+=============
+
+This section provides an overview of the public PyAnsys Math classes,
+functions, and attributes.
+
+.. include:: math.rst
+   :start-line: 5

doc/source/api_ref/math.rst

@@ -0,0 +1,16 @@
+.. _ref_math:
+
+PyAnsys Math
+============
+
+.. currentmodule:: ansys.math.core
+
+.. autosummary::
+   :toctree: _autosummary
+
+   math.AnsMath
+   math.AnsMathObj
+   math.AnsVec
+   math.AnsMat
+   math.AnsSolver
+

doc/source/conf.py

@@ -1,14 +1,15 @@
 """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
 import pyvista
 from sphinx_gallery.sorting import FileNameSortKey
 
-from ansys.math import core as amath
 from ansys.math.core import __version__
+import ansys.math.core.math as pymath
 
 # Manage errors
 pyvista.set_error_output_file("errors.txt")
@@ -26,9 +27,16 @@
 
 # necessary when building the sphinx gallery
 pyvista.BUILDING_GALLERY = True
-amath.BUILDING_GALLERY = True
+pymath.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 = "PyAnsys Math"
 
 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": "ansys-math",
+    "github_version": "main",
+    "doc_path": "doc/source",
+}
+
 # Sphinx extensions
 extensions = [
     "jupyter_sphinx",
@@ -105,17 +123,20 @@
 # Intersphinx mapping
 intersphinx_mapping = {
     "python": ("https://docs.python.org/dev", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/reference", None),
+    "numpy": ("https://numpy.org/devdocs", None),
     # kept here as an example
-    # "scipy": ("https://docs.scipy.org/doc/scipy/reference", None),
-    # "numpy": ("https://numpy.org/devdocs", None),
     # "matplotlib": ("https://matplotlib.org/stable", None),
     # "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None),
     # "pyvista": ("https://docs.pyvista.org/", None),
     # "grpc": ("https://grpc.github.io/grpc/python/", None),
 }
 
+suppress_warnings = ["label.*"]
 # numpydoc configuration
+numpydoc_use_plots = True
 numpydoc_show_class_members = False
+numpydoc_class_members_toctree = False
 numpydoc_xref_param_type = True
 
 # Consider enabling numpydoc validation. See:
@@ -184,18 +205,10 @@
 copybutton_prompt_text = r">>> ?|\.\.\. "
 copybutton_prompt_is_regexp = True
 
-
-html_context = {
-    "display_github": True,  # Integrate GitHub
-    "github_user": "pyansys",
-    "github_repo": "ansys-math",
-    "github_version": "main",
-    "doc_path": "doc/source",
-}
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = "ansysmathdoc"
+htmlhelp_basename = "pyansysmathdoc"
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).