Switch to MyST based documentation

.gitignore

@@ -168,3 +168,4 @@ fabric.properties
 
 ### Project specific
 /build/
+/docs/build/

docs/source/conf.py

@@ -13,10 +13,13 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = []
+extensions = [
+    "myst_parser",
+]
 
 templates_path = ['_templates']
 exclude_patterns = []
+source_suffix = [".rst", ".md"]
 
 
 

docs/source/guides/guide_for_fortran_developers.md

@@ -0,0 +1,64 @@
+# Guide for Fortran developers
+
+## Setting up the developer environment
+
+The only prerequisites before these steps are that you have git installed (which is included on many systems by default) and some version of Conda installed.
+
+1. Clone the repository and enter the cloned project directory.
+
+   > ```sh
+   > git clone https://github.com/golmschenk/eesunhong
+   > cd eesunhong
+   > ```
+
+2. Create a Conda virtual environment with the correct dependencies installed.
+
+   > ```sh
+   > conda env create --file=environments.yml
+   > ```
+
+3. Activate the Conda environment.
+
+   > ```sh
+   > conda activate eesunhong_env
+   > ```
+
+In the future, whenever working on developing `eesunhong`, activate the existing environment with the above line. When you are done working, you can either deactivate the environment with `conda deactivate` or just close the terminal.
+
+## Building
+
+`eesunhong` uses CMake for building. CMake is similar to Make, but allows builds to be much more toolchain agnostic (compiler, operating system, etc) as well as providing many other useful features (such as automatically downloading dependencies). All commands expected from inside the project directory.
+
+To build, first configure the build with:
+
+> ```sh
+> cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
+> ```
+
+Then build with:
+
+> ```sh
+> cmake --build build --config Debug
+> ```
+
+Just the second build command is required for subsequent builds, and will only rebuild changed components.
+
+To clean the build, simply delete the build directory:
+
+> ```sh
+> rm -rf build
+> ```
+
+To build an optimized version, first clean the build, then run the configure and build commands again, but this time replacing `Debug` with `Release`.
+
+To compile using `ifort`, make sure `ifort` is available in the path, then run
+
+> ```sh
+> export FC=ifort
+> ```
+
+prior to the build commands.
+
+## Adding source files
+
+The file specifying which source files to compile, `CMakeLists.txt`, may look somewhat confusing to those unfamiliar to CMake, especially due to the complexity added by importing remote GitHub dependencies and building both a Python library and the main binary executable. For Fortran developers, the main piece you will likely need to change is to add additional source files to be compiled. In most cases, you should add your new source files to the statement starting with `add_executable(eesunhong_main`. If the source files will include functions or routines that should be callable from Python, the should generally be included in the statement starting with `add_library(eesunhong_internal`.

docs/source/index.md

@@ -0,0 +1,41 @@
+% eesunhong documentation master file, created by
+% sphinx-quickstart on Mon Jan  1 22:48:08 2024.
+% You can adapt this file completely to your liking, but it should at least
+% contain the root `toctree` directive.
+
+# Welcome to eesunhong's documentation!
+
+## Installation
+
+To install `eesunhong` use
+
+```shell
+pip install eesunhong
+```
+
+Although not required, as is generally good practice for any development project, we highly recommend creating a separate virtual environment for each distinct project. For example, via Conda, creating a virtual environment for a project using `eesunhong` might look like
+
+```
+conda create -n eesunhong_env python=3.11
+```
+
+Then before working, be sure to activate your environment with
+
+```shell
+conda activate eesunhong_env
+```
+
+Then install `eesunhong` within this environment.
+
+```{toctree}
+:caption: 'Contents:'
+:maxdepth: 2
+
+guides/guide_for_fortran_developers
+```
+
+# Indices and tables
+
+- {ref}`genindex`
+- {ref}`modindex`
+- {ref}`search`