Create Documentation Website

.github/CONTRIBUTING.md

@@ -8,17 +8,19 @@ and feedback from users.
 wish to contribute to GITM. Following these guidelines will ensure a positive
 experience for all involved.
 
-## Outline
-
-- [Opening an Issue](#opening-an-issue)
-  - [Bug Report](#bug-report)
-  - [Feature Requests](#feature-requests)
-- [Pull Requests](#pull-requests)
-  - [Committing Changes](#committing-changes)
-    - [Commit Styling](#commit-styling)
-- [Code Formatting](#code-formatting)
-  - [Automatic/Validating Code Formatting](#automaticvalidating-code-formatting)
-  - [Style Guidelines \& `.fprettify.rc`](#style-guidelines--fprettifyrc)
+- [Contributing Guidelines](#contributing-guidelines)
+  - [Opening an Issue](#opening-an-issue)
+    - [Bug Report](#bug-report)
+    - [Feature Requests](#feature-requests)
+  - [Pull Requests](#pull-requests)
+    - [Committing Changes](#committing-changes)
+      - [Commit Styling](#commit-styling)
+  - [Testing GITM](#testing-gitm)
+  - [Code Formatting](#code-formatting)
+    - [Automatic/Validating Code Formatting](#automaticvalidating-code-formatting)
+    - [Style Guidelines \& `.fprettify.rc`](#style-guidelines--fprettifyrc)
+
+---
 
 ## Opening an Issue
 
@@ -30,15 +32,15 @@ are creating and then modify the contents of the template to describe your issue
 
 ### Bug Report
 
-If you notice a problkem with GITM and are unsure of how to fix it yourself, please
+If you notice a problem with GITM and are unsure of how to fix it yourself, please
 create a bug report detailing the problem. The template has several optional sections,
 so read through them all before adding information to the wrong section.
 
 - **Do not open an issue for problems installing GITM on a specific system.** Since
 there is no way to predict all possible systems which GITM will be used on, details on
 specific systems cannot be provided. Try the steps in the [README](../README.md) first,
-then reach out to #TODO if you need mroe help.
-- Please include enough information to allow a maintainer to reproduce your bug
+then reach out to the development team if you need more help.
+- Please include enough information to allow a maintainer to reproduce your bug,
 only seeing the information in the bug report. Forgetting to attach input files or
 only saying "the code did not run on system X", for example, will result in a delay.
 - Check if another issue is open (or closed) with the same problem. Duplicate issues
@@ -78,7 +80,7 @@ are working on a feature and notice an unrelated bug or typo, create a new branc
 `develop`, fix it, and submit the pull request separately. There is no harm in
 submitting many small pull requests!
 - **Document your changes**. If you are introducing a new feature, please include
-a description of it and its uses in both the documentation (`docs/` folder) and
+a description of it and its uses in both the documentation (`srcDoc/` folder) and
 in comments within the code.
 - **Include new tests**. If you are adding a new feature, please add a sample `UAM.in`
 file with this option enabled in the `srcTests/auto_test/` folder. We do not want future updates
@@ -134,6 +136,19 @@ FEAT: Hydrostatic density implementation.
 Implemented hydrostatic density. (feature)
 ```
 
+## Testing GITM
+
+GITM has a number of tests that are maintained and run automatically on every
+release & pull-request. To run these yourself, run the script `run_all_tests.sh`
+from within `srcTests/auto_test`. New tests can be added by simply creating
+another UAM.in file, and will be run automatically if the file matches the
+pattern `UAM.in.*.test`.
+
+It is best practice to create tests as bugs are fixed. For example, if running
+GITM in a certain configuration causes a crash, it is recommended to create a
+test with this configuration which will help ensure the bug does not sneak back
+in with future development.
+
 ## Code Formatting
 
 GITM now uses a custom implementation of the

.github/workflows/Format-Doc-Test.yml → .github/workflows/Format-and-Test.yml

@@ -48,34 +48,13 @@ jobs:
           cd GITM
           python srcPython/format_GITM.py -l -s -v ${ALL_CHANGED_FILES}
 
-  Documentation:
-    runs-on: ubuntu-latest
-    name: Build Documentation
-    needs: [Format]
-    steps:
-      - name: Clone GITM repository
-        uses: actions/checkout@v4
-      - name: Compile LaTeX document
-        uses: xu-cheng/latex-action@v3
-        with:
-          root_file: manual.tex
-          working_directory: srcDoc
-      - name: Rename GITM Manual
-        run: mv srcDoc/manual.pdf GITM_manual.pdf
-      - name: Upload PDF file
-        uses: actions/upload-artifact@v4
-        with:
-          name: PDF
-          path: GITM_manual.pdf
-          retention-days: 31
-
   Tests:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest]
     name: Run Automatic Tests
-    needs: [Format, Documentation]
+    needs: [Format]
     steps:
       - name: Linux install gfortran & openmpi
         if: runner.os == 'Linux'
@@ -85,6 +64,7 @@ jobs:
         run: |
           brew update
           brew install gcc open-mpi
+          ln -s $(brew --prefix)/bin/gfortran-15 $(brew --prefix)/bin/gfortran
       - name: Clone GITM repository
         uses: actions/checkout@v4
       - name: Run tests on MacOS (no output checking, only one test)

.gitignore

@@ -61,4 +61,5 @@ ext/
 share/component_share 
 util/component_util
 
-src/.version
+src/.version
+gitstatus.txt

.readthedocs.yaml

@@ -0,0 +1,15 @@
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - requirements: srcDoc/requirements.txt

Makefile

@@ -37,9 +37,7 @@ NOMPI:
 	@cd ${NOMPIDIR}; make LIB
 
 VERSION:
-	printf 'character(25), parameter :: GitmVersion = "%s.%s"\n' \
-	"$$(git log -1 --date=format:'%Y%m%d' --pretty='format:%ad')" \
-	"$$(git status --porcelain | grep -v '^??' | wc -l | cut -f1 -d' ')" > src/.version
+	./share/Scripts/Makeversion.sh
 	@echo
 
 GITM:
@@ -87,6 +85,7 @@ clean:
 	if [ -d util ]; then cd util; make --no-print-directory cleanall; fi;
 	if [ -d srcSAMI ]; then cd srcSAMI; make --no-print-directory clean; fi;
 	if [ -d $(EIEDIR) ]; then cd $(EIEDIR); make --no-print-directory cleanall; fi;
+	if [ -f src/.version ]; then rm src/.version; fi
 
 
 distclean: 

README.md

@@ -5,9 +5,9 @@ This is the home of the Global Ionosphere/Thermosphere Model (GITM).
 GITM has been developed in fortran-90. It has been tested with gfortran
 on Linux and MacOS as well as ifort on NASA's Pleiades computer.
 
-The latest version of the documentation can be accessed at:
+For the complete documentation, see [GITM's Read the Docs Page](https://gitm.readthedocs.io).
 
-[![Build Documentation](https://github.com/GITMCode/GITM/actions/workflows/build-docs.yml/badge.svg)](https://github.com/GITMCode/GITM/actions/workflows/build-docs.yml)
+---
 
 <details>
 <summary><b>GITM's default branch recently changed names. To access the latest features, please update your local refs.</b></summary>
@@ -29,38 +29,38 @@ git remote prune origin
 
 </details>
 
-## Dependencies
-
-1. GITM needs MPI to work.
-
 ## Quick Start
 
+> GITM needs MPI to work properly. This can be installed with your system's package manager, or loaded as a `module` on an HPC system.
+> See [the installation guide](https://gitm.readthedocs.io/en/latest/quick_start/#requirements) for more information.
+
 1\. Clone the repository and cd into the repo folder
 
 ```shell
-git clone --recursive https://github.com/GITMCode/GITM
+git clone git@github.com:GITMCode/GITM.git
 ```
 
+Substitute the URL with the `https` link from the "Code" button above if you do not have SSH keys set up.
+
 2\. Go into the repo directory
 
 ```shell
 cd GITM
 ```
 
-3\. Configure the Fortran compiler (version 10)
+3\. Configure the Fortran compiler and download external electrodynamics library
+(gfortran versions 10+)
 
 ```shell
 ./Config.pl -install -earth -compiler=gfortran10
 ```
 
 The biggest issue with the above command is that it assumes that you
-have the gfortran (version 10) compiler and things like mpif90 work
+have the gfortran (version 10+) compiler and things like mpif90 work
 ok.  If you don't have gfortran and mpif90, then you need to get these
 things for your computer.  If you have version 9 or before for gfortran,
 you can do:
 
-3b\. Configure the Fortran compiler (version 9 or below)
-
 ```shell
 ./Config.pl -install -earth -compiler=gfortran
 ```
@@ -69,17 +69,15 @@ In theory, Mars, Venus, Titan, and LV-426 should work.  These are in
 various states of completion, so I wouldn't count on them being
 perfect.
 
-If running on Pleiades (as of March 3, 2022), you need to have these
+If running on Pleiades, you need to have these
 in your start-up script (.cshrc, .bashrc, etc):
 
 ```
-module load comp-intel/2016.2.181
-module load mpi-hpe/mpt
+module load comp-intel
+module load mpi-hpe
 ```
 
-And you can use 3c below to configure the code.
-
-3c\. Configure for Pleiades
+And you can use the below line below to configure the code:
 
 ```shell
 ./Config.pl -install -earth -compiler=ifort
@@ -127,7 +125,7 @@ lon. See below for how to set the resolution.
 > see available options.
 
 > The legacy postprocessors are still available, but are not built by default. To build
-> PostProcess.exe, run `make POST` and the csh script can be found at `src/pGITM`.
+> PostProcess.exe, run `make POST`. The csh script can be found at `src/pGITM`.
 
 9\. Go into the output directory:
 
@@ -200,7 +198,9 @@ team.  For example:
 NCAR. The IGRF code that comes with it is also not developed at UM.
 
 2. Many electrodynamics models (Weimer, Newell's Ovation Prime,
-Mitchell's Ovation SME, others in the util/EMPIRICAL/srcIE directory).
+Mitchell's Ovation SME, others in the 
+[GITMCode/Electrodynamics](https://github.com/GITMCode/Electrodynamics)
+repository).
 
 3. MSIS and IRI, which are in util/EMPIRICAL/srcUA. MSIS is used as a
 lower BC at Earth and was developed at NRL. IRI is used to initialize
@@ -228,3 +228,7 @@ processors, you can change the parameters in `src/ModSize.f90` and adjust the
 number of cells in each block to compensate. For example, you have 8
 processors, so you can adjust `src/ModSize.f90` to have 18 cells in lat and
 lon, then ask for 2 (lat) x 4 (lon) blocks to get 5 deg x 5 deg resolution.
+
+See the 
+[grid page](https://gitm.readthedocs.io/en/latest/grid/#horizontal-resolution)
+in the documentation for more details and some examples.

mkdocs.yml

@@ -0,0 +1,90 @@
+site_name: GITM
+site_url: https://gitm.readthedocs.io
+site_description: >-
+  Official documentation for the Global Ionosphere Thermosphere Model (GITM)
+repo_name: GITMCode/GITM
+repo_url: https://github.com/GITMCode/GITM
+
+theme:
+  # name: readthedocs
+  # name: mkdocs
+  name: material
+  icon:
+    logo: material/earth
+    repo: material/github
+
+  features:
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.footer
+    - toc.integrate
+    - content.code.annotate
+    - content.code.copy
+
+  palette:
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default 
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+
+plugins:
+  - search # allow for search after being built
+  - mermaid2: # cool diagrams
+      javascript: js/mermaid.min.js # local path to mermaid javascript file
+
+markdown_extensions:
+  - pymdownx.extra #footnotes, abbreviations, tables, definitions, etc.
+  - pymdownx.fancylists # lists continuing after breaking for indentation
+  - pymdownx.saneheaders #allows for "#text" to not be parsed as a header
+  - pymdownx.tasklist
+  - markdown_katex # math
+  - admonition # note, warning, etc. blocks
+  - markdown_del_ins # strike-through & insert
+  - markdown_captions # figure captions.
+  - pymdownx.superfences:
+        # make exceptions to highlighting of code:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:mermaid2.fence_mermaid
+
+docs_dir: srcDoc
+
+nav:
+  - Home: index.md
+  - Getting Started: install.md
+  - Inputs:
+    - Common Inputs: common_inputs.md
+    - All Inputs: set_inputs.md
+  - Outputs:
+    - Postprocessing: postprocessing.md
+    - Available Outputs: outputs.md
+    - Plotting Outputs: plotters.md
+  - Internals:
+    - Overview: internals/overview.md
+    - Grid: internals/grid.md
+    - Earth Chemistry: internals/chemistry.md
+    - Electrodynamics: internals/electrodynamics.md
+  - Development:
+    - Site Information: devstuff/devhome.md
+    - Contributing: https://github.com/GITMCode/GITM/blob/main/.github/CONTRIBUTING.md
+    - GITM Developers: https://github.com/GITMCode/GITM/graphs/contributors
+    - Markdown Reference: devstuff/markdown_ref.md
+    - GITM Outline: devstuff/outline.md
+    - Other Useful Links: devstuff/somelinks.md
+  - Getting Help: FAQ/faq.md