From 090849eedcc91ba1b65bed347210ec72a98f38a8 Mon Sep 17 00:00:00 2001 From: jdhughes-usgs Date: Thu, 5 Aug 2021 17:25:04 -0500 Subject: [PATCH] doc: clarify readthedocs versions (#1169) closes #1165 --- .docs/conf.py | 61 ++++++++++++++-- .docs/introduction.rst | 70 +++++++++++-------- .docs/main.rst | 2 + README.md | 9 ++- examples/Tutorials/modflow6/tutorial01_mf6.py | 2 +- flopy/version.py | 18 ++--- 6 files changed, 119 insertions(+), 43 deletions(-) diff --git a/.docs/conf.py b/.docs/conf.py index 907e5cb167..c02022d4fa 100644 --- a/.docs/conf.py +++ b/.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__ diff --git a/.docs/introduction.rst b/.docs/introduction.rst index ae30a7a8c1..7c644234cb 100644 --- a/.docs/introduction.rst +++ b/.docs/introduction.rst @@ -1,11 +1,33 @@ What is FloPy ============= -The FloPy package consists of a set of Python scripts to run MODFLOW, MT3D, SEAWAT and other MODFLOW-related groundwater programs. FloPy enables you to run all these programs with Python scripts. The FloPy project started in 2009 and has grown to a fairly complete set of scripts with a growing user base. FloPy3 was released in December 2014 with a few great enhancements that make FloPy3 backwards incompatible. The first significant change is that FloPy3 uses zero-based indexing everywhere, which means that all layers, rows, columns, and stress periods start numbering at zero. This change was made for consistency as all array-indexing was already zero-based (as are all arrays in Python). This may take a little getting-used-to, but hopefully will avoid confusion in the future. A second significant enhancement concerns the ability to specify time-varying boundary conditions that are specified with a sequence of layer-row-column-values, like the WEL and GHB packages. A variety of flexible and readable ways have been implemented to specify these boundary conditions. FloPy is an open-source project and any assistance is welcomed. Please email the development team if you want to contribute. +The FloPy package consists of a set of Python scripts to run MODFLOW, MT3D, +SEAWAT and other MODFLOW-related groundwater programs. FloPy enables you to +run all these programs with Python scripts. The FloPy project started in 2009 +and has grown to a fairly complete set of scripts with a growing user base. +FloPy3 was released in December 2014 with a few great enhancements that make +FloPy3 backwards incompatible. The first significant change is that FloPy3 +uses zero-based indexing everywhere, which means that all layers, rows, +columns, and stress periods start numbering at zero. This change was made +for consistency as all array-indexing was already zero-based (as are +all arrays in Python). This may take a little getting-used-to, but hopefully +will avoid confusion in the future. A second significant enhancement concerns +the ability to specify time-varying boundary conditions that are specified +with a sequence of layer-row-column-values, like the WEL and GHB packages. +A variety of flexible and readable ways have been implemented to specify these +boundary conditions. + +Recently, FloPy has been further enhanced to include full support for +MODFLOW 6. The majority of recent development has focused on FloPy +functionality for MODFLOW 6, helper functions to use GIS shapefiles and +raster files to create MODFLOW datasets, and common plotting and +export functionality. + +FloPy is an open-source project and any assistance is welcomed. Please email +the development team if you want to contribute. Return to the Github `FloPy `_ website. - FloPy Installation ================== @@ -52,32 +74,24 @@ FloPy Development Team ====================== FloPy is developed by a team of MODFLOW users that have switched over to using -Python for model development and post processing. Members of the team currently -include: - -* Mark Bakker -* Vincent Post -* Joe Hughes -* Chris Langevin -* Jeremy White -* Andy Leaf -* Scott Paulinski -* Josh Larsen -* Mike Toews -* Eric Morway -* Jason Bellino -* Jeff Starn -* Mike Fienen - -with contributions from: - -* Kolja Rotzoll -* Alain Frances -* and others - -Feel free to contact one of us if you would like to participate in FloPy -development. - +Python for model development and post-processing. Members of the team +currently include: + + * Mark Bakker + * Vincent Post + * Joseph D. Hughes + * Christian D. Langevin + * Jeremy T. White + * Andrew T. Leaf + * Scott R. Paulinski + * Jason C. Bellino + * Eric D. Morway + * Michael W. Toews + * Joshua D. Larsen + * Michael N. Fienen + * Jon Jeffrey Starn + * Davíd Brakenhoff + * and others How to Cite =========== diff --git a/.docs/main.rst b/.docs/main.rst index 522973d1ca..95aa7948bc 100644 --- a/.docs/main.rst +++ b/.docs/main.rst @@ -6,6 +6,8 @@ FloPy Documentation =================== +**Documentation for version 3.3.4 --- release candidate** + Return to the Github `FloPy `_ website where the code resides. Contents: diff --git a/README.md b/README.md index 832d5409fb..09358687fa 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,12 @@ The release candidate version can also be installed from the git repository usin Documentation ----------------------------------------------- -FloPy code documentation is available at [https://flopy.readthedocs.io](https://flopy.readthedocs.io) +Documentation is available on **Read the Docs** and includes information +on FloPy; tutorials for using FloPy with MODFLOW 6 and previous versions +of MODFLOW, MT3DMS, MT3D-USGS, MODPATH, and ZONEBUDGET; and code documentation. + + - Read the Docs for the [latest release](https://flopy.readthedocs.io). + - Read the Docs for the [current release candidate](https://flopy.readthedocs.io/en/latest/). Getting Started @@ -140,7 +145,7 @@ How to Cite ##### ***Software/Code citation for FloPy:*** -[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., 2021, FloPy v3.3.4 — release candidate: U.S. Geological Survey Software Release, 18 February 2021, http://dx.doi.org/10.5066/F7BK19FH](http://dx.doi.org/10.5066/F7BK19FH) +[Bakker, Mark, Post, Vincent, Hughes, J. D., Langevin, C. D., White, J. T., Leaf, A. T., Paulinski, S. R., Bellino, J. C., Morway, E. D., Toews, M. W., Larsen, J. D., Fienen, M. N., Starn, J. J., and Brakenhoff, Davíd, 2021, FloPy v3.3.4 — release candidate: U.S. Geological Survey Software Release, 05 August 2021, http://dx.doi.org/10.5066/F7BK19FH](http://dx.doi.org/10.5066/F7BK19FH) MODFLOW Resources diff --git a/examples/Tutorials/modflow6/tutorial01_mf6.py b/examples/Tutorials/modflow6/tutorial01_mf6.py index 8327572674..3de3fca374 100644 --- a/examples/Tutorials/modflow6/tutorial01_mf6.py +++ b/examples/Tutorials/modflow6/tutorial01_mf6.py @@ -56,7 +56,7 @@ # an iterative model solution (`IMS`), which controls how the GWF model is # solved. -# ### Create the Flopy simulation object +# ### Create the FloPy simulation object sim = flopy.mf6.MFSimulation( sim_name=name, exe_name="mf6", version="mf6", sim_ws="." diff --git a/flopy/version.py b/flopy/version.py index fbb9bb458f..1053083335 100644 --- a/flopy/version.py +++ b/flopy/version.py @@ -1,5 +1,5 @@ # flopy version file automatically created using...make-release.py -# created on...February 18, 2021 16:28:18 +# created on...August 05, 2021 14:43:06 major = 3 minor = 3 @@ -8,21 +8,23 @@ __pakname__ = "flopy" -# edit author dictionary as necessary +# edit author dictionary as necessary ( +# in order of commits after Bakker and Post author_dict = { "Mark Bakker": "mark.bakker@tudelft.nl", "Vincent Post": "Vincent.Post@bgr.de", - "Christian D. Langevin": "langevin@usgs.gov", "Joseph D. Hughes": "jdhughes@usgs.gov", - "Jeremy T. White": "jwhite@usgs.gov", + "Christian D. Langevin": "langevin@usgs.gov", + "Jeremy T. White": "jwhite@intera.com", "Andrew T. Leaf": "aleaf@usgs.gov", "Scott R. Paulinski": "spaulinski@usgs.gov", - "Joshua D. Larsen": "jlarsen@usgs.gov", - "Michael W. Toews": "M.Toews@gns.cri.nz", - "Eric D. Morway": "emorway@usgs.gov", "Jason C. Bellino": "jbellino@usgs.gov", - "Jon Jeffrey Starn": "jjstarn@usgs.gov", + "Eric D. Morway": "emorway@usgs.gov", + "Michael W. Toews": "M.Toews@gns.cri.nz", + "Joshua D. Larsen": "jlarsen@usgs.gov", "Michael N. Fienen": "mnfienen@usgs.gov", + "Jon Jeffrey Starn": "jjstarn@usgs.gov", + "Davíd Brakenhoff": "d.brakenhoff@artesia-water.nl", } __author__ = ", ".join(author_dict.keys()) __author_email__ = ", ".join(s for _, s in author_dict.items())