Merge remote-tracking branch 'origin/release3.3.4'

.docs/code.rst

@@ -4,9 +4,22 @@ Flopy Code
 MODFLOW 6
 ---------
 
-MODFLOW 6 Base Packages
+FloPy for MODFLOW 6 allows for the construction of multi-model simulations.
+In order to construct a MODFLOW 6 simulation using FloPy, first construct a
+simulation (MFSimulation) object.  Then construct the MODFLOW 6 models
+(Modflowgwf and Modflowgwt) and the packages, like TDIS, that are associated
+with the simulation.  Finally, construct the packages that are associated with
+each of your models.
+
+
+MODFLOW 6 Base Classes
 ^^^^^^^^^^^^^^^^^^^^^^^
 
+FloPy for MODFLOW 6 is object oriented code that uses inheritance.  The FloPy classes
+used to define different types models and packages share common code that is defined
+in these base classes.
+
+
 Contents:
 
 .. toctree::
@@ -16,9 +29,30 @@ Contents:
    ./source/flopy.mf6.mf*
 
 
+MODFLOW 6 Simulation
+^^^^^^^^^^^^^^^^^^^^
+
+MODFLOW 6 allows you to create simulations that can contain multiple models and
+packages.  The FloPy for MODFLOW 6 simulation classes define functionality that applies
+to the entire MODFLOW 6 simulation.  When using FloPy for MODFLOW 6 the first object
+you will most likely create is a simulation (MFSimulation) object.
+
+Contents:
+
+.. toctree::
+   :glob:
+   :maxdepth: 4
+
+   ./source/flopy.mf6.modflow.mfsimulation
+   :exclude-members: register_model
+
 MODFLOW 6 Simulation Packages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+MODFLOW 6 simulation packages are the packages that are not necessarily tied to a
+specific model and can apply to the entire simulation or a group of models in the
+simulation.
+
 Contents:
 
 .. toctree::
@@ -31,32 +65,112 @@ Contents:
    ./source/flopy.mf6.modflow.mftdis
 
 
-MODFLOW 6 Groundwater Flow Packages
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+MODFLOW 6 Models
+^^^^^^^^^^^^^^^^
+
+MODFLOW 6 supports both groundwater flow (mfgwf.ModflowGwf) and groundwater
+transport (mfgwt.ModflowGwt) models.  FloPy for MODFLOW 6 model objects can be
+constructed after a FloPy simulation (MFSimulation) object has been constructed.
 
 Contents:
 
 .. toctree::
    :glob:
    :maxdepth: 4
 
-   ./source/flopy.mf6.modflow.mfgwf*
+   ./source/flopy.mf6.modflow.mfgwf
+   ./source/flopy.mf6.modflow.mfgwt
 
 
-MODFLOW 6 Groundwater Transport Packages
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+MODFLOW 6 Groundwater Flow Model Packages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+MODFLOW 6 groundwater flow models support a number of required and optional packages.
+Once a MODFLOW 6 groundwater flow model object (mfgwf.ModflowGwf) has been constructed
+various packages associated with the groundwater flow model can be constructed.
 
 Contents:
 
 .. toctree::
    :glob:
    :maxdepth: 4
 
-   ./source/flopy.mf6.modflow.mfgwt*
+   ./source/flopy.mf6.modflow.mfgwfa*
+   ./source/flopy.mf6.modflow.mfgwfb*
+   ./source/flopy.mf6.modflow.mfgwfc*
+   ./source/flopy.mf6.modflow.mfgwfd*
+   ./source/flopy.mf6.modflow.mfgwfe*
+   ./source/flopy.mf6.modflow.mfgwff*
+   ./source/flopy.mf6.modflow.mfgwfg*
+   ./source/flopy.mf6.modflow.mfgwfh*
+   ./source/flopy.mf6.modflow.mfgwfi*
+   ./source/flopy.mf6.modflow.mfgwfj*
+   ./source/flopy.mf6.modflow.mfgwfk*
+   ./source/flopy.mf6.modflow.mfgwfl*
+   ./source/flopy.mf6.modflow.mfgwfm*
+   ./source/flopy.mf6.modflow.mfgwfn*
+   ./source/flopy.mf6.modflow.mfgwfo*
+   ./source/flopy.mf6.modflow.mfgwfp*
+   ./source/flopy.mf6.modflow.mfgwfq*
+   ./source/flopy.mf6.modflow.mfgwfr*
+   ./source/flopy.mf6.modflow.mfgwfs*
+   ./source/flopy.mf6.modflow.mfgwft*
+   ./source/flopy.mf6.modflow.mfgwfu*
+   ./source/flopy.mf6.modflow.mfgwfv*
+   ./source/flopy.mf6.modflow.mfgwfw*
+   ./source/flopy.mf6.modflow.mfgwfx*
+   ./source/flopy.mf6.modflow.mfgwfy*
+   ./source/flopy.mf6.modflow.mfgwfz*
+
+
+MODFLOW 6 Groundwater Transport Model Packages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+MODFLOW 6 groundwater transport models support a number of required and optional packages.
+Once a MODFLOW 6 groundwater transport model object (mfgwt.ModflowGwt) has been constructed
+various packages associated with the groundwater transport model can be constructed.
 
+Contents:
 
-MODFLOW 6 Utilities
-^^^^^^^^^^^^^^^^^^^
+.. toctree::
+   :glob:
+   :maxdepth: 4
+
+   ./source/flopy.mf6.modflow.mfgwta*
+   ./source/flopy.mf6.modflow.mfgwtb*
+   ./source/flopy.mf6.modflow.mfgwtc*
+   ./source/flopy.mf6.modflow.mfgwtd*
+   ./source/flopy.mf6.modflow.mfgwte*
+   ./source/flopy.mf6.modflow.mfgwtf*
+   ./source/flopy.mf6.modflow.mfgwtg*
+   ./source/flopy.mf6.modflow.mfgwth*
+   ./source/flopy.mf6.modflow.mfgwti*
+   ./source/flopy.mf6.modflow.mfgwtj*
+   ./source/flopy.mf6.modflow.mfgwtk*
+   ./source/flopy.mf6.modflow.mfgwtl*
+   ./source/flopy.mf6.modflow.mfgwtm*
+   ./source/flopy.mf6.modflow.mfgwtn*
+   ./source/flopy.mf6.modflow.mfgwto*
+   ./source/flopy.mf6.modflow.mfgwtp*
+   ./source/flopy.mf6.modflow.mfgwtq*
+   ./source/flopy.mf6.modflow.mfgwtr*
+   ./source/flopy.mf6.modflow.mfgwts*
+   ./source/flopy.mf6.modflow.mfgwtt*
+   ./source/flopy.mf6.modflow.mfgwtu*
+   ./source/flopy.mf6.modflow.mfgwtv*
+   ./source/flopy.mf6.modflow.mfgwtw*
+   ./source/flopy.mf6.modflow.mfgwtx*
+   ./source/flopy.mf6.modflow.mfgwty*
+   ./source/flopy.mf6.modflow.mfgwtz*
+
+
+MODFLOW 6 Utility Packages
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+MODFLOW 6 has several utility packages that can be associated with other packages.
+This includes the obs package, which can be used to output model results specific
+to its parent package, and the time series and time array series packages, which
+can be used to provide time series input for other packages.
 
 Contents:
 
@@ -67,6 +181,60 @@ Contents:
    ./source/flopy.mf6.modflow.mfutl*
 
 
+MODFLOW 6 Utility Functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+MODFLOW 6 has several utility functions that can be used to process MODFLOW 6
+results.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 4
+
+   ./source/flopy.mf6.utils.binaryfile_utils.rst
+   ./source/flopy.mf6.utils.binarygrid_util.rst
+   ./source/flopy.mf6.utils.mfobservation.rst
+   ./source/flopy.mf6.utils.output_util.rst
+   ./source/flopy.mf6.utils.postprocessing.rst
+   ./source/flopy.mf6.utils.reference.rst
+   ./source/flopy.mf6.utils.lakpak_utils.rst
+
+
+MODFLOW 6 Data
+^^^^^^^^^^^^^^
+
+FloPy for MODFLOW 6 data objects (MFDataArray, MFDataList, MFDataScalar) are
+automatically constructed by FloPy when you construct a package.  These data
+objects provide an interface for getting MODFLOW 6 data in different formats
+and setting MODFLOW 6 data.
+
+Contents:
+
+.. toctree::
+   :glob:
+   :maxdepth: 4
+
+   ./source/flopy.mf6.data.mfdataarray
+   ./source/flopy.mf6.data.mfdatalist
+   ./source/flopy.mf6.data.mfdatascalar
+
+Build MODFLOW 6 Classes
+^^^^^^^^^^^^^^^^^^^^^^^
+
+MODFLOW 6 FloPy classes can be rebuild from MODFLOW 6 definition files. This
+will allow creation of MODFLOW 6 FloPy classes for development versions of
+MODFLOW 6.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 4
+
+   ./source/flopy.mf6.utils.createpackages.rst
+   ./source/flopy.mf6.utils.generate_classes.rst
+
+
 Previous Versions of MODFLOW
 ----------------------------
 

.docs/conf.py

@@ -15,17 +15,70 @@
 
 # add flopy root directory to the python path
 sys.path.insert(0, os.path.abspath(".."))
-from flopy import __version__
+from flopy import __version__, __author__
 
 # -- determine if running on readthedocs ------------------------------------
 on_rtd = os.environ.get('READTHEDOCS') == 'True'
 
+# -- determine if this version is a release candidate
+with open("../README.md", "r") as f:
+    lines = f.readlines()
+rc_text = ""
+for line in lines:
+    if line.startswith("### Version"):
+        if "release candidate" in line:
+            rc_text = "release candidate"
+        break
+
+# -- update version number in main.rst
+rst_name = "main.rst"
+with open(rst_name, "r") as f:
+    lines = f.readlines()
+with open(rst_name, "w") as f:
+    for line in lines:
+        if line.startswith("**Documentation for version"):
+            line = "**Documentation for version {}".format(__version__)
+            if rc_text != "":
+                line += " --- {}".format(rc_text)
+            line += "**\n"
+        f.write(line)
+
+# -- update authors in introduction.rst
+rst_name = "introduction.rst"
+with open(rst_name, "r") as f:
+    lines = f.readlines()
+tag_start = "FloPy Development Team"
+tag_end = "How to Cite"
+write_line = True
+with open(rst_name, "w") as f:
+    for line in lines:
+        if line.startswith(tag_start):
+            write_line = False
+            # update author list
+            line += (
+                "======================\n\n"
+                "FloPy is developed by a team of MODFLOW users that have "
+                "switched over to using\nPython for model development and "
+                "post-processing.  Members of the team\n"
+                "currently include:\n\n"
+            )
+            authors = __author__.split(sep=",")
+            for author in authors:
+                line += " * {}\n".format(author.strip())
+            line += " * and others\n\n"
+            f.write(line)
+        elif line.startswith(tag_end):
+            write_line = True
+        if write_line:
+            f.write(line)
+
+
 # -- create source rst files ------------------------------------------------
 cmd = "sphinx-apidoc -e -o source/ ../flopy/"
 print(cmd)
 os.system(cmd)
 
-# -- programatically create rst files ---------------------------------------
+# -- programmatically create rst files ---------------------------------------
 cmd = ("python", "create_rstfiles.py")
 print(" ".join(cmd))
 os.system(" ".join(cmd))
@@ -38,8 +91,8 @@
 
 # -- Project information -----------------------------------------------------
 project = "flopy Documentation"
-copyright = "2020, Bakker, Mark, Post, Vincent, Langevin, C. D., Hughes, J. D., White, J. T., Leaf, A. T., Paulinski, S. R., Larsen, J. D., Toews, M. W., Morway, E. D., Bellino, J. C., Starn, J. J., and Fienen, M. N."
-author = "Bakker, Mark, Post, Vincent, Langevin, C. D., Hughes, J. D., White, J. T., Leaf, A. T., Paulinski, S. R., Larsen, J. D., Toews, M. W., Morway, E. D., Bellino, J. C., Starn, J. J., and Fienen, M. N."
+copyright = "2021, {}".format(__author__)
+author = __author__
 
 # The version.
 version = __version__
@@ -125,11 +178,11 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+# html_static_path = ["_static"]
 
 html_theme_options = {
-    "github_url": "https://github.com/modflowpy/flopy",
-    "use_edit_page_button": False,
+    # "github_url": "https://github.com/modflowpy/flopy",
+    # "use_edit_page_button": False,
 }
 
 autosummary_generate = True
@@ -169,7 +222,7 @@
 html_split_index = False
 
 # If true, links to the reST sources are added to the pages.
-# html_show_sourcelink = True
+html_show_sourcelink = False
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
 html_show_sphinx = True

.docs/create_rstfiles.py

@@ -1,8 +1,10 @@
 import os
 
 
-def create_section(f, title, filenames):
-    title = "{} Tutorials".format(title.upper())
+def create_section(f, title, filenames, upper_case=False):
+    if upper_case:
+        title = title.upper()
+    title = "{} Tutorials".format(title)
     line = "{}\n".format(title) + len(title) * "-" + "\n\n"
     line += "Contents:\n\n.. toctree::\n   :maxdepth: 2\n\n"
     for filename in filenames:
@@ -32,14 +34,24 @@ def create_tutorial_rst():
         create_section(f, "MODFLOW 6", tutorial_dict[key])
         keys.remove(key)
 
+    key = "modflow6data"
+    if key in keys:
+        create_section(f, "MODFLOW 6 FloPy Use", tutorial_dict[key])
+        keys.remove(key)
+
+    key = "modflow6output"
+    if key in keys:
+        create_section(f, "MODFLOW 6 Output", tutorial_dict[key])
+        keys.remove(key)
+
     key = "modflow"
     if key in keys:
         create_section(f, "MODFLOW", tutorial_dict[key])
         keys.remove(key)
 
     # create the remaining tutorial sections
     for key in keys:
-        create_section(f, key, tutorial_dict[key])
+        create_section(f, key, tutorial_dict[key], upper_case=True)
 
     # close the file
     f.close()

.docs/create_tutorials.py

@@ -16,6 +16,9 @@ def create_notebooks():
     for dirpath, _, filenames in os.walk(pth):
         py_files += [os.path.join(dirpath, filename) for filename in
                      sorted(filenames) if filename.endswith(".py")]
+    # sort the python files
+    py_files = sorted(py_files)
+
     # copy the python files
     for src in py_files:
         dst = os.path.join(wpth, os.path.basename(src))