Add Sphinx docs (#55)

* add sphinx docs

* switch to installing package

* fix the mock

* also mock numpy

* moved instructions from README to sphinx

* added API docs

* fix bash commands

README.md

@@ -1,52 +1,11 @@
 # cgnsUtilities
 [![Build Status](https://dev.azure.com/mdolab/Public/_apis/build/status/mdolab.cgnsutilities?repoName=mdolab%2Fcgnsutilities&branchName=main)](https://dev.azure.com/mdolab/Public/_build/latest?definitionId=30&repoName=mdolab%2Fcgnsutilities&branchName=main)
+[![Documentation Status](https://readthedocs.com/projects/mdolab-cgnsutilities/badge/?version=latest)](https://mdolab-cgnsutilities.readthedocs-hosted.com/en/latest/?badge=latest)
 [![codecov](https://codecov.io/gh/mdolab/cgnsutilities/branch/main/graph/badge.svg?token=ZCO3MR2LNL)](https://codecov.io/gh/mdolab/cgnsutilities)
 
 This repository contains a single program called `cgns_utils` that
 provides many useful functions for working with cgns grids. 
 
-## Installation Instructions
-
-First, copy the default configuration file to the required name. For example, to use gfortran: 
-
-    cp config/defaults/config.LINUX_GFORTRAN.mk config/config.mk
-
-Open and edit the config file.
-You many have to adjust the `CGNS_INCLUDE_FLAGS` and `CGNS_LINKER_FLAGS` to match your installation of the CGNS library.
-You may also specify the c-compiler with the `CC` variable and the flags for the c-compiler with `CFLAGS`.
-The C-compiler is only used for the compiler `f2py` wrapper.
-The Fortran compiler may be specified with the `FC` variable and the corresponding flags with the `FFLAGS` variable.
-It has been tested with both Intel and GNU Fortran compilers. 
-
-To compile, simply type
-
-    make 
-
-If all goes well, you will see
-
-    Testing if module libcgns_utils can be imported...
-    Module libcgns_utils was successfully imported.
-
-which indicates a successful compilation. 
-
-To install, type
-
-    pip install .
-
-or optionally with the `--user` flag if you are not using a virtual environment.
-A console script called `cgns_utils` is provided, which should be installed automatically and available without modifying your `$PATH`.
-
-## Usage
-
-All of the `cgnsUtilties` functionality is accessible through the `cgns_utils` command.
-To see a list of the available sub-commands, type
-
-    cgns_utils -h
-
-To get further help for a sub-command, type for example:
-
-    cgns_utils scale -h
-
 ## License
 
 Copyright 2020 MDO Lab. See the LICENSE file for details

cgnsutilities/cgnsutilities.py

@@ -1,14 +1,3 @@
-"""
-This is the new gateway program to all of the cgns_utils.
-
-Run cgns_utils -help to get a list of all available options. The basic
-idea is as follows:
-
-                                              | write new file
-read cngs file -> Do some operations on it -> |     .or.
-                                              | write modified file
-Developed by Dr. Gaetan K. W. Kenway
-"""
 import os
 import copy
 import tempfile
@@ -58,22 +47,21 @@ def overwriteBCFamilyWithBC(self, familyName, newBCType, blockIDs=None):
         This is useful because Pointwise specifies boundary conditions on CGNS grids in a way
         that is incompatible with ADflow (family-defined) and these BCs always need to be overwritten.
 
-        Example
-        -------
-        from cgnsutilities.cgnsutilities import Grid, readGrid
-        grid = readGrid("pointwise_vol_grid.cgns")
-        grid.overwriteBCFamilyWithBC('oversetfamily', 'bcoverset', [1,2,4])
-        grid.writeToCGNS("pointwise_vol_grid_converted.cgns")
-
-        Inputs
-        ------
+        Parameters
+        ----------
         familyName : str
             The BC family to overwrite
         newBCType : str
             The new boundary condition to apply
         blockIDs : list of int or None
             The 1-based indices of the blocks to overwrite. None overwrites BCs on all blocks.
 
+        Examples
+        --------
+        >>> from cgnsutilities.cgnsutilities import Grid, readGrid
+        >>> grid = readGrid("pointwise_vol_grid.cgns")
+        >>> grid.overwriteBCFamilyWithBC('oversetfamily', 'bcoverset', [1,2,4])
+        >>> grid.writeToCGNS("pointwise_vol_grid_converted.cgns")
         """
         if newBCType not in BC.keys():
             raise ValueError(f"New BC type '{newBCType}' is not in the cgnsUtilities list of boundary conditions.")
@@ -106,8 +94,8 @@ def getTotalCellsNodes(self):
         """
         Returns the total number of Cells and Nodes in the grid.
 
-        Example
-        -------
+        Examples
+        --------
         To determine the number of cells/nodes in a grid use:
             >>> from cgnsutilities.cgnsutilities import Grid, readGrid
             >>> grid = readGrid("gridfilename.cgns")
@@ -125,8 +113,8 @@ def getWallCellsNodes(self):
         """
         Returns the number of Cells and Nodes on wall boundaries
 
-        Example
-        -------
+        Examples
+        --------
         To determine the number of cells/nodes in a grid use:
             >>> from cgnsutilities.cgnsutilities import Grid, readGrid
             >>> grid = readGrid("gridfilename.cgns")
@@ -2559,7 +2547,8 @@ def __init__(self, arrayName, dType, nDims, dataDims, dataArr):
 class B2B(object):
     """
     Class for storing information related to a Block-to-block or
-    (1to1 in cgns speak) connection. More details at http://cgns.github.io/CGNS_docs_current/sids/cnct.html#GridConnectivity1to1.
+    (1to1 in cgns speak) connection. More details can be found
+    `here <http://cgns.github.io/CGNS_docs_current/sids/cnct.html#GridConnectivity1to1>`__.
 
     Parameters
     ----------

doc/API.rst

@@ -0,0 +1,4 @@
+API
+===
+.. automodule:: cgnsutilities.cgnsutilities
+    :members:

doc/CLI.rst

@@ -0,0 +1,7 @@
+Command Line Interface
+======================
+
+.. argparse::
+   :module: cgnsutilities.cgns_utils
+   :func: get_parser
+   :prog: cgns_utils

doc/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/conf.py

@@ -0,0 +1,25 @@
+from sphinx_mdolab_theme.config import *
+
+# -- Path setup --------------------------------------------------------------
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+from unittest.mock import MagicMock
+
+sys.path.insert(0, os.path.abspath("../"))
+
+extensions.extend(["sphinxarg.ext"])
+
+# -- Project information -----------------------------------------------------
+
+project = "CGNS Utilities"
+
+
+# We have to mock some stuff
+# and sphinxarg.ext does NOT use the autodoc mock feature
+
+for mod in ["cgnsutilities.libcgns_utils", "numpy"]:
+    sys.modules[mod] = MagicMock()

doc/index.rst

@@ -0,0 +1,18 @@
+.. CGNS Utilities documentation master file, created by
+   sphinx-quickstart on Mon Mar 29 10:19:14 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+==============
+CGNS Utilities
+==============
+cgnsUtilities is a collection of CLI program and utility functions for working with CGNS grids.
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   install
+   API
+   CLI

doc/install.rst

@@ -0,0 +1,37 @@
+Installation Instructions
+=========================
+
+First, copy the default configuration file to the required name. For example, to use gfortran:
+
+.. prompt:: bash
+
+    cp config/defaults/config.LINUX_GFORTRAN.mk config/config.mk
+
+Open and edit the config file.
+You many have to adjust the ``CGNS_INCLUDE_FLAGS`` and ``CGNS_LINKER_FLAGS`` to match your installation of the CGNS library.
+You may also specify the C compiler with the ``CC`` variable and the flags for the C compiler with ``CFLAGS``.
+The C-compiler is only used for the compiler ``f2py`` wrapper.
+The Fortran compiler may be specified with the ``FC`` variable and the corresponding flags with the ``FFLAGS`` variable.
+It has been tested with both Intel and GNU Fortran compilers.
+
+To compile, simply type
+
+.. prompt:: bash
+
+    make 
+
+If all goes well, you will see::
+
+    Testing if module libcgns_utils can be imported...
+    Module libcgns_utils was successfully imported.
+
+which indicates a successful compilation.
+
+To install, type
+
+.. prompt:: bash
+
+    pip install .
+
+or optionally with the ``--user`` flag if you are not using a virtual environment.
+A console script called ``cgns_utils``` is provided, which should be installed automatically and available without modifying your ``$PATH``.

doc/requirements.txt

@@ -0,0 +1,2 @@
+sphinx_mdolab_theme
+sphinx-argparse