docs(rtd): include developer guide section, troubleshoot rendering (#1889)

The styleguide is missing from the RTD site, try specifying RST and MD suffixes explicitly. And introduce developer guide section with styleguide, DEVELOPER.md, and CONTRIBUTING.md.

Author: wpbonelli

.build_rtd_docs/conf.py

@@ -56,6 +56,25 @@
 # copy the file
 shutil.copy(src, dst)
 
+# -- copy developer docs
+dstdir = "_dev"
+fpth = "DEVELOPER.md"
+src = os.path.join("..", fpth)
+dst = os.path.join(dstdir, fpth)
+# clean up an existing _mf6run directory
+if os.path.isdir(dstdir):
+    shutil.rmtree(dstdir)
+# make the directory
+os.makedirs(dstdir)
+# copy the file
+shutil.copy(src, dst)
+
+# -- copy contributor docs
+fpth = "CONTRIBUTING.md"
+src = os.path.join("..", fpth)
+dst = os.path.join(dstdir, fpth)
+shutil.copy(src, dst)
+
 # -- copy deprecations markdown ---------------------------------------------
 print("Copy the deprecations table")
 dstdir = "_mf6run"
@@ -126,6 +145,8 @@
 # # Tell sphinx what the pygments highlight language should be.
 # highlight_language = 'fortran'
 
+source_suffix = {".rst": "restructuredtext", ".md": "markdown"}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 

.build_rtd_docs/dev.rst

@@ -0,0 +1,12 @@
+Developer Guide
+---------------
+
+This section includes developer instructions and conventions.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   _dev/CONTRIBUTING.md
+   _dev/DEVELOPER.md
+   styleguide.md

.build_rtd_docs/index.rst

@@ -15,5 +15,5 @@ Contents:
    _mf6run/run-time-comparison.md
    _mf6run/deprecations.md
    mf6io
-   styleguide.md
+   dev
 

.build_rtd_docs/styleguide.md

@@ -1,4 +1,4 @@
-# Style Guide
+# Fortran 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.
 

DEVELOPER.md

@@ -11,11 +11,8 @@ To build and test a parallel version of the program, first read the instructions
   - [Git](#git)
   - [Fortran compiler](#fortran-compiler)
     - [GNU Fortran](#gnu-fortran)
-      - [Linux](#linux)
-      - [macOS](#macos)
-      - [Windows](#windows)
     - [Intel Fortran](#intel-fortran)
-      - [Windows](#windows-1)
+      - [Windows](#windows)
     - [Compiler compatibility](#compiler-compatibility)
       - [Compile](#compile)
       - [Test](#test)
@@ -27,9 +24,6 @@ To build and test a parallel version of the program, first read the instructions
       - [`flopy`](#flopy)
       - [`modflow-devtools`](#modflow-devtools)
   - [Optional tools](#optional-tools)
-    - [GNU Make](#gnu-make)
-    - [Visual Studio](#visual-studio)
-    - [Doxygen & LaTeX](#doxygen--latex)
 - [Installation](#installation)
 - [Building](#building)
 - [Formatting](#formatting)
@@ -90,12 +84,12 @@ GNU Fortran or Intel Fortran compilers can be used to build MODFLOW 6. It may be
 
 GNU Fortran can be installed on all three major platforms.
 
-##### Linux
+*Linux*
 
 - Fedora-based: `dnf install gcc-gfortran`
 - Debian-based: `apt install gfortran`
 
-##### macOS
+*macOS*
 
 - [Homebrew](https://brew.sh/): `brew install gcc@13`
 - [MacPorts](https://www.macports.org/): `sudo port install gcc13`
@@ -108,7 +102,7 @@ export LDFLAGS="$LDFLAGS -Wl,-ld_classic"
 
 See [this ticket](https://github.com/mesonbuild/meson/issues/12282) on the Meson repository for more information.
 
-##### Windows
+*Windows*
 
 [Minimalist GNU for Windows](https://www.mingw-w64.org/) is the recommended way to obtain the GCC toolchain on Windows. Several MinGW distributions are available.
 
@@ -224,15 +218,15 @@ The tests use a set of shared fixtures and utilities provided by the [`modflow-d
 
 Some other tools are useful but not required to develop MODFLOW 6.
 
-#### GNU Make
+*GNU Make*
 
 This repository provides makefiles, generated by `mfpymake`, which can be used to build MODFLOW 6 with [GNU Make](https://www.gnu.org/software/make/). For further instructions we refer to the [GNU Make Manual](https://www.gnu.org/software/make/manual/).
 
-#### Visual Studio
+*Visual Studio*
 
 Visual Studio installers can be downloaded from the [official website](https://visualstudio.microsoft.com/). MODFLOW 6 solution files can be found in the `msvs` folder.
 
-#### Doxygen & LaTeX
+*Doxygen & LaTeX*
 
 [Doxygen](https://www.doxygen.nl/index.html) is used to generate the [MODFLOW 6 source code documentation](https://modflow-usgs.github.io/modflow6/). [Graphviz](https://graphviz.org/) is used by doxygen to produce source code diagrams. [LaTeX](https://www.latex-project.org/) is used to generate the MODFLOW 6 release notes and Input/Output documents (docs/mf6io/mf6io.nightlybuild).