Use numpydoc (#583)

* add templates

* add templates in earnest

* fix docbuild

* post doc updates

* finish post and math docstring cleanup

* fix docstring warnings

* in progress add validations

* finalize doc cleanup

* cleanup CI; fix flake8 error

Author: akaszynski

.ci/azure-pipelines.yml

@@ -18,7 +18,7 @@ trigger:
 jobs:
 - job: Linux
   variables:
-    python.version: '3.8'  # limited to < Python 3.8 due to VTK req
+    python.version: '3.8'
     DISPLAY: ':99.0'
     MAPDL.IMAGE: 'docker.pkg.github.com/pyansys/pymapdl/mapdl'
     PYMAPDL_PORT: 32771  # default of 50052 does not work on azure devops

.flake8

@@ -1,5 +1,5 @@
 [flake8]
-exclude = venv, __init__.py
+exclude = venv, __init__.py, build
 # To be added after refactoring code to be compliant: E501, F401, W191, W291, W293
 select = W391, E115, E117, E122, E124, E125, E225, E231, E301, E303, F403
 count = True

.github/workflows/ci-build.yml .github/workflows/doc-build.yml.github/workflows/ci-build.yml renamed to .github/workflows/doc-build.yml

@@ -1,7 +1,15 @@
 # Build documentation
 name: Documentation Build
 
-on: [push, pull_request, workflow_dispatch]
+on:
+  pull_request:
+  workflow_dispatch:
+  push:
+    tags:
+      - "*"
+    branches:
+      - main
+
 
 jobs:
   docs_build:
@@ -19,9 +27,9 @@ jobs:
       - uses: actions/checkout@v2
 
       - name: Setup Python
-        uses: actions/setup-python@v2.1.4
+        uses: actions/setup-python@v2
         with:
-          python-version: 3.7
+          python-version: 3.8
 
       - name: Install, start, and test the virtual framebuffer
         run: |
@@ -47,27 +55,31 @@ jobs:
           LICENSE_SERVER: ${{ secrets.LICENSE_SERVER }}
           GH_USERNAME: ${{ secrets.GH_USERNAME }}
           GH_PAT: ${{ secrets.REPO_DOWNLOAD_PAT }}
+
+      - name: Install OS packages
+        run: |
+          sudo apt update
+          sudo apt install zip pandoc -qy
   
       - name: Build Documentation
         run: |
-          sudo apt install pandoc -qy
           pip install -r requirements_docs.txt
-          make -C doc html
-        env:
-          PYMAPDL_CI_NO_AUTODOC: True
+          make -C doc html SPHINXOPTS="-j auto -w build_errors.txt -N"
 
-      - name: Full Documentation Build
-        if: startsWith(github.ref, 'refs/tags/')
+      # Verify that sphinx generates no warnings
+      - name: Check for warnings
+        run: python doc/print_errors.py
+
+      - name: Zip documentation
         run: |
-          sudo apt install pandoc -qy
-          pip install -r requirements_docs.txt
-          make -C doc html
-  
+          cd doc/build/html
+          zip -r PyMAPDL_documentation.zip *
+
       - name: Upload Documentation
-        uses: actions/upload-artifact@v2.2.1
+        uses: actions/upload-artifact@v2
         with:
           name: Documentation
-          path: doc/build/html
+          path: doc/build/html/PyMAPDL_documentation.zip
           retention-days: 7
 
       - name: Deploy

.github/workflows/smoke-tests.yml

@@ -1,7 +1,14 @@
 name: Smoke Tests
 # verify we can install on a variety of Python versions and OSes
 
-on: [push, pull_request, workflow_dispatch]
+on:
+  pull_request:
+  workflow_dispatch:
+  push:
+    tags:
+      - "*"
+    branches:
+      - main
 
 jobs:
   testimport:

.github/workflows/style.yml

@@ -1,7 +1,14 @@
 # check spelling, codestyle
 name: Style Check
 
-on: [push, pull_request, workflow_dispatch]
+on:
+  pull_request:
+  workflow_dispatch:
+  push:
+    tags:
+      - "*"
+    branches:
+      - main
 
 jobs:
   build:

.gitignore

@@ -33,9 +33,11 @@ pyansys/Interface.py
 doc/source/examples/*
 *.out
 *.tar.gz
+*.mypy_cache
 
-# autogenerated docs
+# docs
 _autosummary
+doc/build_errors.txt
 
 
 # Testing

Makefile

@@ -4,33 +4,31 @@ CODESPELL_DIRS ?= ./
 CODESPELL_SKIP ?= "*.pyc,*.txt,*.gif,*.png,*.jpg,*.js,*.html,*.doctree,*.ttf,*.woff,*.woff2,*.eot,*.mp4,*.inv,*.pickle,*.ipynb,flycheck*,./.git/*,./.hypothesis/*,*.yml,./doc/build/*,./doc/images/*,./dist/*,*~,.hypothesis*,./doc/source/examples/*,*cover,*.dat,*.mac,\#*,build,./docker/mapdl/v*,./factory/*,./ansys/mapdl/core/mapdl_functions.py,PKG-INFO,*.mypy_cache/*,./docker/mapdl/*"
 CODESPELL_IGNORE ?= "ignore_words.txt"
 
-all: doctest
-
-doctest: codespell
+codestyle: codespell flake8
 
 codespell:
 	@echo "Running codespell"
 	@codespell $(CODESPELL_DIRS) -S $(CODESPELL_SKIP) -I $(CODESPELL_IGNORE)
 
 pydocstyle:
 	@echo "Running pydocstyle"
-	@pydocstyle ansys.mapdl
+	@pydocstyle ansys.mapdl.core
 
 doctest-modules:
 	@echo "Runnnig module doctesting"
-	pytest -v --doctest-modules ansys.mapdl
+	pytest -v --doctest-modules ansys.mapdl.core
 
 coverage:
 	@echo "Running coverage"
-	@pytest -v --cov ansys.mapdl
+	@pytest -v --cov ansys.mapdl.core
 
 coverage-xml:
 	@echo "Reporting XML coverage"
-	@pytest -v --cov ansys.mapdl --cov-report xml
+	@pytest -v --cov ansys.mapdl.core --cov-report xml
 
 coverage-html:
 	@echo "Reporting HTML coverage"
-	@pytest -v --cov ansys.mapdl --cov-report html
+	@pytest -v --cov ansys.mapdl.core --cov-report html
 
 flake8:
 	@echo "Running flake8"

ansys/mapdl/core/_commands/apdl/abbreviations.py

@@ -3,7 +3,7 @@ class Abbreviations:
     def abbr(self, abbr="", string="", **kwargs):
         """Defines an abbreviation.
 
-        APDL Command: *ABBR
+        APDL Command: ``*ABBR``
 
         Parameters
         ----------
@@ -14,13 +14,15 @@ def abbr(self, abbr="", string="", **kwargs):
             which is the same as an ANSYS command.
 
         string
-            String of characters (60 maximum) represented by Abbr.  Cannot
-            include a $ or any of the commands C***,  /COM,  /GOPR,  /NOPR,
-            /QUIT,  /UI, or  *END.  Parameter names and commands of the *DO and
-            Use the *IF groups may not be abbreviated. If String is blank, the
-            abbreviation is deleted. To abbreviate multiple commands, create an
-            "unknown command" macro or define String to execute a macro file
-            [*USE] containing the desired commands.
+            String of characters (60 maximum) represented by Abbr.
+            Cannot include a $ or any of the commands ``C***``, /COM,
+            /GOPR, /NOPR, /QUIT, /UI, or ``*END``.
+
+            Use the ``*IF`` groups may not be abbreviated. If String
+            is blank, the abbreviation is deleted. To abbreviate
+            multiple commands, create an "unknown command" macro or
+            define String to execute a macro file [``*USE``]
+            containing the desired commands.
 
         Notes
         -----
@@ -31,8 +33,8 @@ def abbr(self, abbr="", string="", **kwargs):
         any time and are available throughout the program. Abbreviations may be
         redefined or deleted at any time.
 
-        Use *STATUS to display the current list of abbreviations. For
-        abbreviations repeated with *REPEAT, substitution occurs before the
+        Use ``*STATUS`` to display the current list of abbreviations. For
+        abbreviations repeated with ``*REPEAT``, substitution occurs before the
         repeat increments are applied. There are a number of abbreviations that
         are predefined by the program (these can be deleted by using the blank
         String option described above). Note that String will be written to the
@@ -136,7 +138,7 @@ def ucmd(self, cmd="", srnum="", **kwargs):
         dependent) subroutine.  This feature allows user-defined commands to be
         programmed into the ANSYS program.  Once programmed, this command can
         be input to the program like other commands, and can also be included
-        in the ANSYS start-up file.  See *ULIB for another way of defining user
+        in the ANSYS start-up file.  See ``*ULIB`` for another way of defining user
         commands.
 
         Up to 10 subroutines are available for user-defined commands (USER01 to