docs/conversion-to-mkdocs (#460)

* remove a merge conflict statement that was missed * add base requirements for mkdocs * set up configuration for API docs * start work on porting user guide to mkdocs * add custom styling and contact page * begin work on porting tutorial to mkdocs * add new examples page * move old sphinx docs to their own folder (*delete later*) * modify some admonitions to be success * modify hello examples page and port step 3 of tutorial to mkdocs * fix typo in hello example * finish porting step 4 of tutorial to mkdocs * port part 5 of the tutorial to mkdocs * copy faq and contributing from old docs * port step 6 of tutorial to mkdocs * remove unused prereq * port step 7 of tutorial to mkdocs * add more detailed instructions on contributing * move venv page into installation and add spack instructions too * add configuration docs * add content to user guide landing page * port celery page to mkdocs * rearrange configuration pages to add in merlin server configuration instructions * port command line page to mkdocs * finish new landing page * change size of merlin logo * port variables page to mkdocs * fix broken links to configuration page * port FAQ to mkdocs * fix incorrect requirement name * update CHANGELOG * attempt to get docs to build through readthedocs * port docker page to mkdocs * port contributing guide to mkdocs * add new 'running studies' page * add path changes to images * add a page on how to interpret study output * add page on the spec file * remove old sphinx docs that are no longer needed * added README to docs and updated CHANGELOG * fix copyright and hello_samples tree * rearrange images/stylesheets and statements that use them * add suggestions from Luc and Joe * add tcsh instructions for venv activation * add Charle's suggestions for the landing page * change tcsh mentions to csh
LLNL · Jan 25, 2024 · 40930c2 · 40930c2
1 parent 642f925
commit 40930c2
Show file tree

Hide file tree

Showing 127 changed files with 9,115 additions and 6,121 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -5,11 +5,11 @@ build:
   tools:
     python: "3.8"
 
-sphinx:
-  configuration: docs/source/conf.py
-
 python:
   install:
     - requirements: docs/requirements.txt
 
+mkdocs:
+  fail_on_warning: false
+
 formats: [pdf]
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -16,6 +16,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - The `merlin monitor` command will now keep an allocation up if the queues are empty and workers are still processing tasks
 - Add the restart keyword to the specification docs
 
+### Changed
+- The entire documentation has been ported to MkDocs and re-organized
+  - *Dark Mode*
+  - New "Getting Started" example for a simple setup tutorial
+  - More detail on configuration instructions
+  - There's now a full page on installation instructions
+  - More detail on explaining the spec file
+  - More detail with the CLI page
+  - New "Running Studies" page to explain different ways to run studies, restart them, and accomplish command line substitution
+  - New "Interpreting Output" page to help users understand how the output workspace is generated in more detail
+  - New "Examples" page has been added
+  - Updated "FAQ" page to include more links to helpful locations throughout the documentation
+  - Set up a place to store API docs
+  - New "Contact" page with info on reaching Merlin devs
+
 ## [1.11.1]
 ### Fixed
 - Typo in `batch.py` that caused lsf launches to fail (`ALL_SGPUS` changed to `ALL_GPUS`)

diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,44 @@
+# Guide to Merlin Documentation
+
+Merlin uses [MkDocs](https://www.mkdocs.org/) to generate its documentation and [Read the Docs](https://about.readthedocs.com/?ref=readthedocs.com) to host it. This README will detail important information on handling the documentation.
+
+## How to Build the Documentation
+
+Ensure you're at the root of the Merlin repository:
+
+```bash
+cd /path/to/merlin/
+```
+
+Install the documentation with:
+
+```bash
+pip install -r docs/requirements.txt
+```
+
+Build the documentation with:
+
+```bash
+mkdocs serve
+```
+
+Once up and running, MkDocs should provide a message telling you where your browser is connected (this is typically `http://127.0.0.1:8000/`). If you're using VSCode, you should be able to `ctrl+click` on the address to open the browser window. An example is shown below:
+
+```bash
+(venv_name) [user@machine:merlin]$ mkdocs serve
+INFO    -  Building documentation...
+INFO    -  Cleaning site directory
+WARNING -  Excluding 'README.md' from the site because it conflicts with 'index.md'.
+WARNING -  A relative path to 'api_reference/' is included in the 'nav' configuration, which is not found in the documentation files.
+INFO    -  Documentation built in 3.24 seconds
+INFO    -  [09:16:00] Watching paths for changes: 'docs', 'mkdocs.yml'
+INFO    -  [09:16:00] Serving on http://127.0.0.1:8000/
+```
+
+## Configuring the Documentation
+
+MkDocs relies on an `mkdocs.yml` file for almost everything to do with configuration. See [their Configuration documentation](https://www.mkdocs.org/user-guide/configuration/) for more information.
+
+## How Do API Docs Work?
+
+Coming soon...
diff --git a/docs/api_reference/index.md b/docs/api_reference/index.md
@@ -0,0 +1,5 @@
+# Merlin API Reference
+
+Coming soon!
+
+<!-- Welcome to the Application Program Interface (API) Reference Guide for Merlin! This comprehensive guide is designed to provide developers with a detailed understanding of the various modules, classes, and functions available within the Merlin API. -->
diff --git a/docs/assets/images/hello-samples-tree.png b/docs/assets/images/hello-samples-tree.png
diff --git a/docs/assets/images/interpreting_output/basic-merlin-info-workspace.png b/docs/assets/images/interpreting_output/basic-merlin-info-workspace.png
diff --git a/docs/assets/images/interpreting_output/basic-step-workspace.png b/docs/assets/images/interpreting_output/basic-step-workspace.png
diff --git a/docs/assets/images/interpreting_output/merlin-info-with-samples.png b/docs/assets/images/interpreting_output/merlin-info-with-samples.png
diff --git a/docs/assets/images/interpreting_output/modified-hierarchy-structure.png b/docs/assets/images/interpreting_output/modified-hierarchy-structure.png
diff --git a/docs/assets/images/interpreting_output/two-level-sample-hierarchy.png b/docs/assets/images/interpreting_output/two-level-sample-hierarchy.png
diff --git a/docs/assets/images/interpreting_output/workspace-with-params-and-samples.png b/docs/assets/images/interpreting_output/workspace-with-params-and-samples.png
diff --git a/docs/assets/images/interpreting_output/workspace-with-params.png b/docs/assets/images/interpreting_output/workspace-with-params.png
diff --git a/docs/assets/images/interpreting_output/workspace-with-samples.png b/docs/assets/images/interpreting_output/workspace-with-samples.png
diff --git a/docs/images/merlin_arch.png → docs/assets/images/merlin_arch.png b/docs/images/merlin_arch.png → docs/assets/images/merlin_arch.png
diff --git a/docs/images/merlin.png → docs/assets/images/merlin_banner.png b/docs/images/merlin.png → docs/assets/images/merlin_banner.png
diff --git a/docs/assets/images/merlin_banner_white.png b/docs/assets/images/merlin_banner_white.png
diff --git a/docs/images/merlin_icon.png → docs/assets/images/merlin_icon.png b/docs/images/merlin_icon.png → docs/assets/images/merlin_icon.png
diff --git a/docs/assets/images/running_studies/current-node-launch.png b/docs/assets/images/running_studies/current-node-launch.png
diff --git a/docs/assets/images/running_studies/iterative-diagram.png b/docs/assets/images/running_studies/iterative-diagram.png
diff --git a/docs/assets/images/running_studies/merlin-run-diagram.png b/docs/assets/images/running_studies/merlin-run-diagram.png
diff --git a/docs/assets/images/running_studies/parallel-launch.png b/docs/assets/images/running_studies/parallel-launch.png
diff --git a/docs/assets/images/running_studies/producer-consumer-model.png b/docs/assets/images/running_studies/producer-consumer-model.png
diff --git a/docs/assets/images/running_studies/worker-server-communication.png b/docs/assets/images/running_studies/worker-server-communication.png
diff --git a/...es/advanced_topics/cumulative_results.png → ...al/advanced_topics/cumulative_results.png b/...es/advanced_topics/cumulative_results.png → ...al/advanced_topics/cumulative_results.png
diff --git a/docs/source/modules/hello_world/dag1.png → ...sets/images/tutorial/hello_world/dag1.png b/docs/source/modules/hello_world/dag1.png → ...sets/images/tutorial/hello_world/dag1.png
diff --git a/docs/source/modules/hello_world/dag2.png → ...sets/images/tutorial/hello_world/dag2.png b/docs/source/modules/hello_world/dag2.png → ...sets/images/tutorial/hello_world/dag2.png
diff --git a/docs/source/modules/hello_world/dag3.png → ...sets/images/tutorial/hello_world/dag3.png b/docs/source/modules/hello_world/dag3.png → ...sets/images/tutorial/hello_world/dag3.png
diff --git a/docs/source/modules/hello_world/dag4.png → ...sets/images/tutorial/hello_world/dag4.png b/docs/source/modules/hello_world/dag4.png → ...sets/images/tutorial/hello_world/dag4.png
diff --git a/...rce/modules/hello_world/merlin_output.png → ...es/tutorial/hello_world/merlin_output.png b/...rce/modules/hello_world/merlin_output.png → ...es/tutorial/hello_world/merlin_output.png
diff --git a/...ce/modules/hello_world/merlin_output2.png → ...s/tutorial/hello_world/merlin_output2.png b/...ce/modules/hello_world/merlin_output2.png → ...s/tutorial/hello_world/merlin_output2.png
diff --git a/docs/images/central_coordination.png → ...ial/introduction/central_coordination.png b/docs/images/central_coordination.png → ...ial/introduction/central_coordination.png
diff --git a/docs/images/external_coordination.png → ...al/introduction/external_coordination.png b/docs/images/external_coordination.png → ...al/introduction/external_coordination.png
diff --git a/docs/images/internal_coordination.png → ...al/introduction/internal_coordination.png b/docs/images/internal_coordination.png → ...al/introduction/internal_coordination.png
diff --git a/docs/images/merlin_run.png → ...ages/tutorial/introduction/merlin_run.png b/docs/images/merlin_run.png → ...ages/tutorial/introduction/merlin_run.png
diff --git a/docs/images/task_creation_rate.png → ...orial/introduction/task_creation_rate.png b/docs/images/task_creation_rate.png → ...orial/introduction/task_creation_rate.png
diff --git a/...ules/run_simulation/lid-driven-stable.png → ...rial/run_simulation/lid-driven-stable.png b/...ules/run_simulation/lid-driven-stable.png → ...rial/run_simulation/lid-driven-stable.png
diff --git a/...e/modules/run_simulation/openfoam_dag.png → .../tutorial/run_simulation/openfoam_dag.png b/...e/modules/run_simulation/openfoam_dag.png → .../tutorial/run_simulation/openfoam_dag.png
diff --git a/...les/run_simulation/openfoam_wf_output.png → ...ial/run_simulation/openfoam_wf_output.png b/...les/run_simulation/openfoam_wf_output.png → ...ial/run_simulation/openfoam_wf_output.png
diff --git a/...rce/modules/run_simulation/prediction.png → ...es/tutorial/run_simulation/prediction.png b/...rce/modules/run_simulation/prediction.png → ...es/tutorial/run_simulation/prediction.png
diff --git a/docs/source/modules/run_simulation/setup.png → .../images/tutorial/run_simulation/setup.png b/docs/source/modules/run_simulation/setup.png → .../images/tutorial/run_simulation/setup.png
diff --git a/docs/assets/javascripts/swap_lp_image.js b/docs/assets/javascripts/swap_lp_image.js
@@ -0,0 +1,26 @@
+/*
+ * This script is for swapping the landing page image between
+ * one with black text (for light mode) and one with white
+ * text (for dark mode).
+ */
+
+function swapLandingPageImage() {
+    // Get the current theme (should be "slate" or "default")
+    const colorSchemeValue = document.body.getAttribute("data-md-color-scheme");
+
+    // Get the image element
+    const imageElement = document.getElementById("landing-page-image");
+
+    // Paths for light/dark mode images
+    const lightModeImgPath = "assets/images/merlin_banner.png";
+    const darkModeImgPath = "assets/images/merlin_banner_white.png";
+
+    // Set the image source based on the color scheme
+    imageElement.src = colorSchemeValue == "slate" ? darkModeImgPath : lightModeImgPath;
+}
+
+// Set up an observer to watch for theme changes
+const observer = new MutationObserver(swapLandingPageImage);
+const targetNode = document.body;
+const config = {attributes: true, childList: true};
+observer.observe(targetNode, config);
diff --git a/docs/assets/stylesheets/extra.css b/docs/assets/stylesheets/extra.css
@@ -0,0 +1,8 @@
+[data-md-color-scheme=slate] {
+    --md-default-bg-color: hsla(var(--md-hue),15%,22%,1);
+}
+
+[data-md-color-primary=black] .md-button--primary {
+    background-color: hsla(202, 97%, 34%, 1);  /* This is the same as #036BA9 (the hex color of Merlin's hat logo) */
+    border-color: hsla(202, 97%, 34%, 1);
+}
diff --git a/docs/contact.md b/docs/contact.md
@@ -0,0 +1,21 @@
+---
+hide:
+  - navigation
+---
+
+# Contact Us
+
+!!! question "Have a Question?"
+
+    :material-email: [[email protected]](mailto:[email protected])
+
+    :simple-microsoftteams: LC Teams Channels:
+
+    - [Merlin Support Page](https://teams.microsoft.com/l/team/19%3a8efc6658663c46aca4bfca4f11df7eb3%40thread.skype/conversations?groupId=7c7f88bc-2485-460f-90e2-4f6880b5ed3e&tenantId=a722dec9-ae4e-4ae3-9d75-fd66e2680a63)
+
+    - [WEAVE's Merlin Support Page](https://teams.microsoft.com/l/channel/19%3aa677f3ebd1d9463b9128e9609a5b4177%40thread.tacv2/Merlin?groupId=a56ae26c-fe55-4e8e-8773-dd7975f648a4&tenantId=a722dec9-ae4e-4ae3-9d75-fd66e2680a63)
+
+
+!!! note "Submit an Issue"
+
+    :simple-github: [Report an Issue on GitHub](https://github.com/LLNL/merlin/issues)
diff --git a/docs/examples/feature_demo.md b/docs/examples/feature_demo.md
@@ -0,0 +1,3 @@
+# Feature Demo Examples
+
+Coming soon!
diff --git a/docs/examples/flux.md b/docs/examples/flux.md
@@ -0,0 +1,3 @@
+# Flux Examples
+
+Coming soon!