Fix the documentation

.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
-==========
+AnsysMath
+=========
 
 |pyansys| |pypi| |PyPIact| |GH-CI| |codecov| |zenodo| |MIT| |black|
 
@@ -30,36 +30,75 @@ Ansys Math
   :alt: black
 
 
-Overview
---------
+AnsysMath is a Python repository holding Ansys mathematical libraries.
+To use them, you must have a local installation of Ansys.
 
-Ansys Math is a Python repository holding Ansys mathematical libraries.
+For more information on getting a licensed copy of Ansys, 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 
+`AnsysMath GitHub <amath_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:
+
+.. 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 AnsysMath from Python by running:
+
+.. code:: python
+
+    import ansys.math.core.math as amath
+
+    # Start AnsysMath
+    mm = amath.AnsMath()
+    print(mm)
+
+
+If you see a response from the server, congratulations. You're ready
+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 Ansys versions earlier than 2021 R1.
 
-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 section provides an overview 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.AnsMath
+   math.AnsMathObj
+   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": "ansys-math",
+    "github_version": "main",
+    "doc_path": "doc/source",
+}
+
 # Sphinx extensions
 extensions = [
     "jupyter_sphinx",
@@ -105,15 +123,16 @@
 # 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_show_class_members = False
 numpydoc_xref_param_type = True
@@ -184,14 +203,6 @@
 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.

doc/source/contributing/index.rst

@@ -0,0 +1,83 @@
+.. _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 before attempting to contribute to PyMAPDL.
+
+The following contribution information is specific to AnsysMath.
+
+Cloning the repository
+--------------------------------
+
+Run this code to clone and install the latest version of AnsysMath 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 PyAnsys 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 the 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
+  blacken-docs.............................................................Passed
+  isort....................................................................Passed
+  flake8...................................................................Passed
+  codespell................................................................Passed
+  check for merge conflicts................................................Passed
+  debug statements (python)................................................Passed
+  Validate GitHub Workflows................................................Passed
+