docs: add style guide, tidy dev/contrib docs, update docs sites (#1870)

Add styleguide section and guidelines/conventions to RTD site, transcribed from Feb. 2024 developer meeting. Include very minimal sample module, maybe others can extend?

Clean up DEVELOPER.md and CONTRIBUTING.md. Describe fprettify and check_format.py usage, update outdated parts of contributing guide, update outdated TOCs, don't detail git commands, contributors can discover these elsewhere.

Remove update_fortran_style.py with view to moving related efforts to fprettify eventually. Existing code can be updated manually/opportunistically for now.

Minor improvements/cleanup to docs sites including:

* rename RTD site "MODFLOW 6 Program Documentation" -> "MODFLOW 6"
* rename api ref site "Source Code Documentation" -> "API Reference"
* update api ref site brief to "USGS Modular Hydrologic Model"
*  update section names in TOCs
* bump copyright date years
* minor explication

Merging now to get an initial render up on RTD, @Manangka has platform-specific fixes and more to come in a separate PR.

.build_rtd_docs/Doxyfile

@@ -43,7 +43,7 @@ PROJECT_NUMBER         = "version 6.6.0.dev0"
 # for a project that appears at the top of each page and should give viewer a
 # quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          = "MODFLOW 6 Code Documentation"
+PROJECT_BRIEF          = "USGS Modular Hydrologic Model"
 
 # With the PROJECT_LOGO tag one can specify a logo or an icon that is included
 # in the documentation. The maximum height of the logo should not exceed 55

.build_rtd_docs/MAINPAGE.md

@@ -1,7 +1,7 @@
-# MODFLOW 6 Source Code Documentation
+# Overview
 
 The documentation here is extracted from the source code by [doxygen](https://www.doxygen.nl/index.html).
 
-The source code repository is hosted at https://github.com/MODFLOW-USGS/modflow6 where full details can be found.
+The source code repository is hosted [on GitHub](https://github.com/MODFLOW-USGS/modflow6).
 
-MODFLOW 6 usage documentation can be found at https://modflow6.readthedocs.io/en/latest/
+This documentation is intended for MODFLOW 6 contributors and users of the MODFLOW 6 library/API. MODFLOW 6 usage documentation can be found [on ReadTheDocs](https://modflow6.readthedocs.io/en/latest/).

.build_rtd_docs/conf.py

@@ -91,8 +91,8 @@
 
 # -- Project information -----------------------------------------------------
 
-project = "MODFLOW 6 Program Documentation"
-copyright = "2023, MODFLOW Development Team"
+project = "MODFLOW 6"
+copyright = "2024, MODFLOW Development Team"
 author = "MODFLOW Development Team"
 
 # -- Project version ---------------------------------------------------------

.build_rtd_docs/index.rst

@@ -11,8 +11,9 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
-   MODFLOW 6 Source Code Documentation <https://modflow-usgs.github.io/modflow6/>
-   mf6io
+   API Reference <https://modflow-usgs.github.io/modflow6/>
    _mf6run/run-time-comparison.md
    _mf6run/deprecations.md
+   mf6io
+   styleguide.md
 

.build_rtd_docs/mf6io.rst

@@ -1,8 +1,9 @@
-MODFLOW 6 Input Guide
----------------------
+Input Guide
+-----------
 
-The latest version of the complete MODFLOW 6 input output guide can be found
+The latest version of the complete MODFLOW 6 input/output guide can be found
 `here <https://github.com/MODFLOW-USGS/modflow6-nightly-build/releases/>`_.
+This section enumerates and describes MODFLOW 6 input files.
 
 Simulation
 ^^^^^^^^^^

.build_rtd_docs/styleguide.md

@@ -0,0 +1,77 @@
+# Style Guide
+
+The goal of this guide is to provide a standard for MODFLOW 6 contributors to follow, in pursuit of consistent, readable, well-organized, and unsurprising source code.
+
+MODFLOW 6 is written in Fortran — largely Fortran 2003, with sparse use of a few 2008 language features. This guide assumes familiarity with the Fortran language.
+
+## Amendments
+
+Suggestions to change or extend the style conventions are welcome. Suggestions should be accompanied by a good case for the change. Bear in mind that a goal of this guide is to minimize time spent thinking about questions of style.
+
+## Conventions
+
+* Use `CamelCase` for source file names.
+* Use `CamelCase` for module and derived type names.
+* Use a noun or noun phrase for module and derived type names.
+* Use `snake_case` for procedure names.
+* Use a verb or verb phrase for procedure names.
+* End module names with `...Module`.
+* Derived type names may, but need not, end with `...Type`.
+* If a source file exists primarily to host a module, name the source file and module identically, except for trailing `...Module`.
+* If a module exists primarily to host a type, name the module and type identically, except for trailing `...Module` and `...Type`.
+* Include the module/subroutine/function name in `end module`, `end subroutine` and `end function` statements.
+* Don't end procedures with a `return` statement; use `return` only to return early.
+* Avoid `goto` statements.
+* Use `implicit none` in all modules.
+* Avoid `implicit none` in procedures except where necessary (e.g. interface bodies).
+* Don't use implicit dummy arguments or local variables.
+* Make modules `private` by default. Mark `public` types and procedures explicitly.
+* Specify precision for logicals, integers and reals with the data types defined in `src/Utilities/kind.f90`.
+* Avoid empty comments.
+* Avoid comments starting with `--`.
+* Include blank lines between:
+  * module declaration and `use...` statements
+  * `use...` statements and procedure declarations
+  * derived type declaration and member variables
+  * member variables and `contains` statements
+* Prefer explicitly specified imports with `use ..., only: ...`, rather than merely `use ...`.
+* Prefer importing items used throughout a module with a module-scoped `use` statement, rather than separately in multiple procedures.
+* Use [Doxygen format](https://www.doxygen.nl/manual/docblocks.html#fortranblocks) for docstrings. For dummy arguments, use either `@param ...` above the signature or `!< ...` next to the dummy argument.
+* Name type-bound procedures' first dummy argument `this`. A suitable docstring is `!< this instance`.
+* Avoid deeply nested control structures where possible.
+* Prefer verbose names, except where the meaning is obvious from context or precedent. E.g., well-known index variables (`i`, `j`, `m`, `n`).
+* Use named constants. Avoid [magic numbers](https://en.wikipedia.org/wiki/Magic_number_(programming)).
+
+## Sample Module
+
+Below is a minimal module demonstrating some (but not all) of the conventions.
+
+```f90
+module SampleModule
+
+  use KindModule, only: DP, I4B, LGP
+  use ConstantsModule, only: DPI
+
+  implicit none
+  private
+  public :: run_sample
+
+contains
+
+  subroutine run_sample(verbose)
+    logical(LGP), intent(in) :: verbose
+    integer(I4B) :: answer
+    real(DP) :: pi
+
+    answer = 42
+    pi = DPI
+
+    if (verbose) then
+      print *, 'pi: ', pi
+      print *, 'answer to the ultimate question of life,'&
+               ' the universe, and everything: ', answer
+    end if
+  end subroutine run_sample
+
+end module SampleModule
+```

.doc/conf.py

@@ -48,8 +48,8 @@
 
 # -- Project information -----------------------------------------------------
 
-project = "MODFLOW 6 Program Documentation"
-copyright = "2023, MODFLOW Development Team"
+project = "MODFLOW 6"
+copyright = "2024, MODFLOW Development Team"
 author = "MODFLOW Development Team"
 
 # -- General configuration ---------------------------------------------------