initial CI attempt

Author: akaszynski

.github/workflows/ci-build.yml

@@ -0,0 +1,50 @@
+name: Documentation Build
+on: [push, pull_request, workflow_dispatch]
+
+jobs:
+  docs_build:
+    runs-on: ubuntu-20.04
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Setup Python
+        uses: actions/[email protected]
+        with:
+          python-version: 3.8
+
+      - name: Build HTML Documentation
+        run: |
+          pip install -r requirements_docs.txt --disable-pip-version-check
+          make -C doc html SPHINXOPTS="-W"
+          touch doc/build/html/.nojekyll
+          echo "dev.docs.pyansys.com" > doc/build/html/CNAME
+  
+      - name: Build PDF Documentation
+        run: |
+          sudo apt install apt-get install -y texlive-latex-base
+          make -C doc latexpdf
+
+      - name: Upload HTML Documentation
+        uses: actions/[email protected]
+        with:
+          name: Documentation
+          path: doc/build/html
+          retention-days: 7
+
+      - name: Upload PDF Documentation
+        uses: actions/[email protected]
+        with:
+          name: Documentation
+          path: doc/build/latex/*.pdf
+          retention-days: 7
+
+      - name: Deploy to gh-pages
+        if: github.ref == 'refs/heads/main'
+        uses: JamesIves/[email protected]
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BRANCH: gh-pages
+          FOLDER: doc/build/html
+          CLEAN: true
+          single-commit: true

.github/workflows/style.yml

@@ -0,0 +1,21 @@
+# check spelling, codestyle
+name: Style Check
+
+on: [push, pull_request, workflow_dispatch]
+
+jobs:
+  stylecheck:
+    runs-on: ubuntu-20.04
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Setup Python
+        uses: actions/[email protected]
+        with:
+          python-version: 3.8
+
+      - name: Check Style
+        run: |
+          pip install -r requirements_style.txt --disable-pip-version-check
+          make

README.rst

@@ -1,30 +1,10 @@
-Introduction
-############
+PyAnsys Developer's Guide
+#########################
 
-Through the PyAnsys project, Ansys provides Python libraries that
-expose Ansys technologies to the Python ecosystem. These libraries 
-are more than reusable scripts. They are clear, concise, and 
-maintainable APIs and interfaces. Their useful functions, classes, 
-and plugins eliminate the need to write scripts and code from scratch. 
+This guide serves as the central document for:
 
-These libraries play a vital role in:
-
-- Application automation
-- Machine learning
-- Postprocessing
-- Data visualization
-- Workflow orchestrations
-- Data manipulation and export
-
-
-Purpose
-#######
-The PyAnsys project is the central site for:
-
-- Ansys developers who want to create and "own" libraries
+- Ansys developers who want to create and "own" libraries.
 - Anyone in the Python community who wants to contribute to a 
-  library
+  library.
 - Anyone who is interested in learning more about the PyAnsys 
-  project and libraries
-
-
+  project and libraries.

doc/source/conf.py

@@ -1,19 +1,16 @@
-from pyansys_sphinx_theme import __version__
+from datetime import datetime
 
 # Project information
-project = 'pyansys_sphinx_theme'
-copyright = '2021, ANSYS'
-author = 'PyAnsys Open Source Developers'
-release = version = __version__
+project = 'PyAnsys Developers Guide'
+copyright = f'{datetime.now().year}, ANSYS'
+author = 'ANSYS, Inc.'
+release = version = '0.1.dev0'
 
-# optionally use the default pyansys logo
 html_logo = 'https://docs.pyansys.com/_static/pyansys-logo-black-cropped.png'
-
 html_theme = 'pyansys_sphinx_theme'
 
-# specify the location of your github repo
 html_theme_options = {
-    "github_url": "https://github.com/pyansys/pyansys-sphinx-theme",
+    "github_url": "https://github.com/pyansys/about",
     "show_prev_next": False
 }
 
@@ -30,3 +27,40 @@
 # The master toctree document.
 master_doc = 'index'
 
+
+master_doc = 'index'
+
+latex_elements = {}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc,
+     f'pyansys_dev_guide_v{version}.tex',
+     "PyAnsys Developer's Guide",
+     author,
+     'manual'),
+]
+
+
+# # -- Options for manual page output ------------------------------------------
+
+# # One entry per manual page. List of tuples
+# # (source start file, name, description, authors, manual section).
+# man_pages = [
+#     (master_doc, 'ansys.mapdl.core', 'ansys.mapdl.core Documentation',
+#      [author], 1)
+# ]
+
+
+# # -- Options for Texinfo output ----------------------------------------------
+
+# # Grouping the document tree into Texinfo files. List of tuples
+# # (source start file, target name, title, author,
+# #  dir menu entry, description, category)
+# texinfo_documents = [
+#     (master_doc, 'ansys.mapdl.core', 'ansys.mapdl.core Documentation',
+#      author, 'ansys.mapdl.core', 'Pythonic interface to MAPDL using gRPC',
+#      'Engineering Software'),
+# ]

doc/source/documentation/class_documentation.rst

@@ -4,17 +4,15 @@ Class Documentation
 There are two main ways of using Sphinx to document an API class:
 
 * Manually describe "how" and "why" to use a class in either 
-  a "User Guide" or an example within the library's documentation 
+  a "User Guide" or an example within the library's documentation .
 * Automatically generate API documentation for classes using the 
-  ``autoclass`` or ``autosummary`` directive
+  ``autoclass`` or ``autosummary`` directive.
 
 Manual Documentation
 --------------------
 
 To manually describe the "how" and "why" usage of a class, use the 
-``.. code:: python`` directive:
-
-.. code::
+``.. code:: python`` directive::
 
    Initialize ``my_module.MyClass`` with initial parameters. These
    parameters are automatically assigned to the class.
@@ -26,6 +24,8 @@ To manually describe the "how" and "why" usage of a class, use the
        >>> my_obj.parm1
        'apple'
 
+This will be rendered as:
+
 Initialize ``my_module.MyClass`` with initial parameters.  These
 parameters are automatically assigned to the class.
 
@@ -43,22 +43,18 @@ Auto-Generated Documentation
 To automatically genereate class descriptions, use either the ``autoclass``  
 or ``autosummary`` directive.
 
-For simple classes, you can use the ``autoclass`` directive:
-
-
-.. code::
+For simple classes, you can use the ``autoclass`` directive::
 
    .. autoclass:: pyansys_sphinx_theme.samples.ExampleClass
        :members:
 
+Which is rendered as:
 
 .. autoclass:: pyansys_sphinx_theme.samples.ExampleClass
     :members:
 
 For complex classes with many methods, you should use 
-the ``autosummary`` directive:
-
-.. code::
+the ``autosummary`` directive::
 
    .. autoclass:: pyansys_sphinx_theme.samples.Complex
 

doc/source/documentation/docstrings.rst

@@ -1,12 +1,60 @@
-Docstrings
-##########
+.. _docstrings:
 
-When writing docstrings for PyAnsys libraries, you should pick either 
-the `numpydoc`_ or `googledoc`_ documentation style. Adhering to the 
-selected style permits usage of the `sphinx.ext.napoleon
-<https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html>`_
-extension, which is included in Sphinx version 1.3 and later.
+Docstring Standards
+###################
+When writing docstrings for PyAnsys libraries, use the `numpydoc`_
+documentation style. To use `numpydoc`_ add the following to your
+``conf.py``:
 
+.. code:: python
+
+  extensions = ['numpydoc',
+                # other extensions
+  ]
+
+
+Minimum Requirements
+--------------------
+PyAnsys libary docstrings contain at a minimum the following
+`numpydoc`_ sections:
+
+* `Short description <https://numpydoc.readthedocs.io/en/latest/format.html#short-summary>`_.
+* `Extended Summary <https://numpydoc.readthedocs.io/en/latest/format.html#extended-summary>`_ (if applicable)
+* `Parameters <https://numpydoc.readthedocs.io/en/latest/format.html#parameters>`_ if applicable
+* `Returns <https://numpydoc.readthedocs.io/en/latest/format.html#returns>`_ if applicable
+* `Examples <https://numpydoc.readthedocs.io/en/latest/format.html#examples>`_
+
+These sections should follow the numpydoc standards.  To avoid
+inconsistencies between PyAnsys libaries, adhere to the following
+additional standards:
+
+
+Parameters
+~~~~~~~~~~
+Always specify the type, and whenever necessary, provide the full class name::
+
+  Parameters
+  ----------
+  my_obj : :class:`ansys.<product>.<library>.FooClass`
+      Description of FooClass.
+  some_int : int
+      Some interger value.
+
+.. note::
+   These parameter descriptions have punctuation. 
+
+
+Returns
+~~~~~~~
+Returns section contains only the return type and no the name and type::
+
+  Returns
+  -------
+  int
+      Description of some return value.
+
+Example Docstrings
+------------------
 Methods and functions should generally be documented with the
 ``Examples`` docstring section to make the usage of the method or
 function clear.  Here is a sample function:
@@ -25,12 +73,28 @@ This directive renders the sample function as:
 .. autofunction:: pyansys_sphinx_theme.sample_func.func
 
 
+Validation
+----------
+Enable validation of docstrings during the sphinx build by adding the
+following line to ``conf.py``::
+
+  numpydoc_validation_checks = {"GL08"}
+
+This will issue the following warning for any objects without a docstring::
+
+  "The object does not have a docstring"
+
+The ``"GL08"`` code is required at minimum for PyAnsys projects.
+Other codes may be enforced at a later date; for a full listing see
+`numpydoc Validation Check
+<https://numpydoc.readthedocs.io/en/latest/validation.html#validation>`_.
+
+
 Additional Information
 ----------------------
-Additional examples and notes regarding Numpy or Google docstrings can
-be found at `sphinx.ext.napoleon
-<https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html>`_. 
-A consistent documentation style should be followed whenever possible.
+Additional examples and notes can be found at `numpydoc`_.  Reference
+their documentation as the primary source of information regarding
+docstring styles aside from the directives noted here.
 
 .. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html
 .. _googledoc: https://google.github.io/styleguide/

doc/source/documentation/index.rst

@@ -1,11 +1,36 @@
-Documentation
-#############
-Good documentation drives library adoption and usage.
+API Documentation
+#################
+Good documentation drives library adoption and usage and is the
+foundation for a good developer experience.  Even with the best
+interfaces and the most functional product, no one will adopt the API
+if they don't know how to use it or if they aren't convinced by the
+documentation or examples they are presented with.
+
+Good API documentation provides the following:
+
+* Increased adoption and improved experience for the developers using
+  the API or libary.
+* Reduction in the time spent on-boarding new users (both contributors
+  and users of the project).
+* Better maintainance of the codebase.  The time spent reading the
+  source is often orders of magnitude greater than the time spent
+  writing it.  Well documented code (both in user-facing docstrings
+  and developer comments) pays dividends in code maintaince.
+* Reduces the amount of time spent understanding the features API.
+
+The documentation for a PyAnsys libary should contain the following
+
+* Module, class, method, and function documentation strings.  See
+  :ref:`docstrings`.
+* Full examples gallery.  See `PyMAPDL Examples
+  <https://mapdldocs.pyansys.com/examples/index.html>`_
+* User guide.
+* Link to this contributing guide.
 
 .. toctree::
    :hidden:
    :maxdepth: 3
 
    docstrings
    class_documentation
-   coding_style
+   coding_style