diff --git a/.docker/README.md b/.docker/README.md
new file mode 100644
index 0000000..3980144
--- /dev/null
+++ b/.docker/README.md
@@ -0,0 +1,3 @@
+# `.docker`
+
+This directory contains files that are specific to the container-based development environment of this repository.
diff --git a/.docker/dev.nginx.conf b/.docker/dev.nginx.conf
new file mode 100644
index 0000000..1e7b350
--- /dev/null
+++ b/.docker/dev.nginx.conf
@@ -0,0 +1,46 @@
+# This is an Nginx configuration file used for previewing the website locally.
+# It maps top-level paths to the containers that serve the associated resources.
+# The hostnames here match the service names defined in `docker-compose.yml`.
+
+events {}
+
+http {
+ server {
+ listen 80;
+
+ # Legacy documentation.
+ location /legacy/ {
+ proxy_pass http://legacy-nmdc-documentation:8000/;
+ }
+
+ # Redirect `/legacy` (exact) to `/legacy/`.
+ location = /legacy {
+ rewrite ^ $scheme://$http_host/legacy/ redirect;
+ }
+
+ # Runtime documentation.
+ location /runtime/ {
+ proxy_pass http://runtime-documentation:8000/;
+ }
+
+ # Redirect `/runtime` (exact) to `/runtime/`.
+ location = /runtime {
+ rewrite ^ $scheme://$http_host/runtime/ redirect;
+ }
+
+ # Workflow documentation.
+ location /workflows/ {
+ proxy_pass http://workflow-documentation:8000/;
+ }
+
+ # Redirect `/workflows` (exact) to `/workflows/`.
+ location = /workflows {
+ rewrite ^ $scheme://$http_host/workflows/ redirect;
+ }
+
+ # Current NMDC documentation.
+ location / {
+ proxy_pass http://nmdc-documentation:8000/;
+ }
+ }
+}
diff --git a/.github/workflows/fetch-and-compile-workflow-documentation.yml b/.github/workflows/fetch-and-compile-workflow-documentation.yml
index 93a080f..4d016e0 100644
--- a/.github/workflows/fetch-and-compile-workflow-documentation.yml
+++ b/.github/workflows/fetch-and-compile-workflow-documentation.yml
@@ -27,14 +27,14 @@ jobs:
#
- name: Fetch documentation sources and arrange into chapters
run: |
- chmod +x ./src/workflow_docs/fetch_docs_sources.sh
- ./src/workflow_docs/fetch_docs_sources.sh
+ chmod +x ./src/ingesters/workflow_docs/fetch_docs_sources.sh
+ ./src/ingesters/workflow_docs/fetch_docs_sources.sh
- name: Introduce additional source documents and a configuration file
run: |
- cp -r src/workflow_docs/metagenome_workflow_overview/docs /tmp/book/src/chapters/1_Metagenome_Workflow_Overview
- cp src/workflow_docs/overview.rst /tmp/book/src/chapters/overview.rst
- cp src/workflow_docs/index.rst /tmp/book/src/index.rst
- cp src/workflow_docs/conf.py /tmp/book/src/conf.py
+ cp -r src/ingesters/workflow_docs/metagenome_workflow_overview/docs /tmp/book/src/chapters/1_Metagenome_Workflow_Overview
+ cp src/ingesters/workflow_docs/overview.rst /tmp/book/src/chapters/overview.rst
+ cp src/ingesters/workflow_docs/index.rst /tmp/book/src/index.rst
+ cp src/ingesters/workflow_docs/conf.py /tmp/book/src/conf.py
- name: Compile source documents into HTML
run: sphinx-build --builder html /tmp/book/src ${{ github.workspace }}/_dist
# Upload the result as an "artifact" so it can then be downloaded and used by another job.
diff --git a/README.md b/README.md
index 5e46fa9..102d596 100644
--- a/README.md
+++ b/README.md
@@ -221,7 +221,7 @@ docker compose up --detach workflow-documentation
```
If you **only** make changes to the documentation source files that reside in _this_ repository
-(i.e. those in `src/workflow_docs`), then you can issue this sequence of commands instead,
+(i.e. those in `src/ingesters/workflow_docs`), then you can issue this sequence of commands instead,
which will allow Docker to _avoid refetching_ the source files from the upstream repos:
```shell
diff --git a/content/assets/img/hero.webp b/content/assets/img/hero.webp
deleted file mode 100644
index 678800b..0000000
Binary files a/content/assets/img/hero.webp and /dev/null differ
diff --git a/content/assets/img/logo-mark.svg b/content/assets/img/logo-mark.svg
deleted file mode 100644
index 0116625..0000000
--- a/content/assets/img/logo-mark.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/content/assets/img/logo-text.svg b/content/assets/img/logo-text.svg
deleted file mode 100644
index 642360f..0000000
--- a/content/assets/img/logo-text.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/content/assets/img/undraw_dashboard_re_3b76.svg b/content/assets/img/undraw_dashboard_re_3b76.svg
deleted file mode 100644
index 0cc858e..0000000
--- a/content/assets/img/undraw_dashboard_re_3b76.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/content/assets/img/undraw_data_processing_yrrv.svg b/content/assets/img/undraw_data_processing_yrrv.svg
deleted file mode 100644
index 8c342d0..0000000
--- a/content/assets/img/undraw_data_processing_yrrv.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/content/assets/img/undraw_text_files_au1q.svg b/content/assets/img/undraw_text_files_au1q.svg
deleted file mode 100644
index 64f61b0..0000000
--- a/content/assets/img/undraw_text_files_au1q.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/content/assets/index.js b/content/assets/index.js
deleted file mode 100644
index e2934a9..0000000
--- a/content/assets/index.js
+++ /dev/null
@@ -1,16 +0,0 @@
-(function () {
- /**
- * Create a banner and mount it to the DOM as the first element inside the `body`.
- *
- * @param innerHTML {string} The HTML content you want the banner to contain.
- */
- function displayBanner(innerHTML = "") {
- const divEl = document.createElement("div");
- divEl.style.backgroundColor = "red";
- divEl.style.textAlign = "center";
- divEl.innerHTML = innerHTML;
- document.body.insertBefore(divEl, document.body.firstChild);
- }
-
- displayBanner('This website is in early development. You can access our production documentation here.');
-})();
\ No newline at end of file
diff --git a/content/assets/favicon.ico b/content/nmdc/src/_static/favicon.ico
similarity index 100%
rename from content/assets/favicon.ico
rename to content/nmdc/src/_static/favicon.ico
diff --git a/content/nmdc/src/_static/js/index.js b/content/nmdc/src/_static/js/index.js
new file mode 100644
index 0000000..ac09f14
--- /dev/null
+++ b/content/nmdc/src/_static/js/index.js
@@ -0,0 +1,39 @@
+(function () {
+ /**
+ * Create a banner and mount it to the DOM as the first element inside the `body`.
+ *
+ * @param innerHTML {string} The HTML content you want the banner to contain.
+ */
+ function displayBanner(innerHTML = "") {
+ const sphinxRTDSidebarEl = document.querySelector('.wy-side-nav-search');
+ const zIndexOfSphinxRTDSidebar = sphinxRTDSidebarEl !== null ? parseInt(window.getComputedStyle(sphinxRTDSidebarEl).zIndex) : 0;
+
+ const divEl = document.createElement("div");
+ divEl.style.backgroundColor = "red";
+ divEl.style.textAlign = "center";
+ divEl.style.zIndex = `${zIndexOfSphinxRTDSidebar + 1}`;
+ divEl.style.position = "relative";
+ divEl.style.paddingBottom = "2px";
+ divEl.innerHTML = innerHTML;
+ document.body.insertBefore(divEl, document.body.firstChild);
+
+ // Now that we've mounted the banner to the DOM, get its height in pixels and give the sidebar's search area
+ // that same number of pixels of top margin; that way, the banner won't cover that element. Also, do the same
+ // thing whenever the browser's width changes, since the banner's height could change in that situation, too.
+ sphinxRTDSidebarEl.style.marginTop = window.getComputedStyle(divEl).height;
+ addEventListener("resize", () => {
+ sphinxRTDSidebarEl.style.marginTop = window.getComputedStyle(divEl).height;
+ });
+ }
+
+ // Register a callback function to run when the web page has fully loaded.
+ window.addEventListener("load", (event) => {
+ displayBanner('This website is in early development. You can access our production documentation here.');
+ });
+
+ displayBanner(`
+ This website is in early development.
+ You can access our production documentation
+ here.
+ `);
+})();
\ No newline at end of file
diff --git a/content/nmdc/src/conf.py b/content/nmdc/src/conf.py
index cd9e757..5729545 100644
--- a/content/nmdc/src/conf.py
+++ b/content/nmdc/src/conf.py
@@ -34,7 +34,7 @@
extensions = [
'myst_parser',
'sphinx_markdown_tables',
- 'sphinx_reredirects'
+ 'sphinx_reredirects',
]
# source_suffix = '.rst'
@@ -68,6 +68,16 @@
]
html_logo = "_static/images/nmdc-logo-bg-white.png"
+# Register a custom favicon for the website.
+# Reference: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_favicon
+html_favicon = "_static/images/favicon.ico"
+
+# Register a custom JavaScript script for the website to load.
+# Reference: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_js_files
+html_js_files = [
+ "js/index.js"
+]
+
# -- Redirects ------------------------------------------
# Redirect old schema documentation URLs to the schema documentation
@@ -77,4 +87,16 @@
"workflows.html": "/workflows/",
"reference/metadata/xylene": "https://w3id.org/nmdc/xylene", # the latter redirects to: https://microbiomedata.github.io/nmdc-schema/xylene/
"reference/metadata/*": "https://w3id.org/nmdc/nmdc",
-}
\ No newline at end of file
+}
+
+# -- Sphinx Read The Docs Theme -------------------------
+#
+# Configure "Edit on GitHub" links.
+# Reference: https://docs.readthedocs.io/en/stable/guides/edit-source-links-sphinx.html#github
+html_context = {
+ "display_github": True,
+ "github_user": "microbiomedata",
+ "github_repo": "docs",
+ "github_version": "main",
+ "conf_py_path": "/content/nmdc/src/", # path to directory containing `conf.py` file
+}
diff --git a/docker-compose.yml b/docker-compose.yml
index fc9292e..ae19f3b 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -7,7 +7,7 @@ services:
ports:
- "5001:8000"
volumes:
- - ./legacy/nmdc-documentation:/app
+ - ./legacy/nmdc-documentation/src:/app/src
nmdc-documentation:
# Use the container image built from `content/nmdc/Dockerfile`.
@@ -17,12 +17,12 @@ services:
ports:
- "5002:8000"
volumes:
- - ./content/nmdc:/app
+ - ./content/nmdc/src:/app/src
runtime-documentation:
- # Use the container image built from `src/runtime_docs/Dockerfile`.
+ # Use the container image built from `src/ingesters/runtime_docs/Dockerfile`.
build:
- context: src/runtime_docs
+ context: src/ingesters/runtime_docs
dockerfile: Dockerfile
ports:
- "5003:8000"
@@ -30,7 +30,7 @@ services:
workflow-documentation:
# Use the container image built from `src/workflow_docs/Dockerfile`.
build:
- context: src/workflow_docs
+ context: src/ingesters/workflow_docs
dockerfile: Dockerfile
ports:
- "5004:8000"
@@ -46,4 +46,4 @@ services:
ports:
- "5000:80"
volumes:
- - ./src/home_website/dev.nginx.conf:/etc/nginx/nginx.conf:ro
+ - ./.docker/dev.nginx.conf:/etc/nginx/nginx.conf:ro
diff --git a/legacy/nmdc-documentation/src/_static/favicon.ico b/legacy/nmdc-documentation/src/_static/favicon.ico
new file mode 100644
index 0000000..dff6056
Binary files /dev/null and b/legacy/nmdc-documentation/src/_static/favicon.ico differ
diff --git a/legacy/nmdc-documentation/src/_static/js/index.js b/legacy/nmdc-documentation/src/_static/js/index.js
new file mode 100644
index 0000000..7348f7e
--- /dev/null
+++ b/legacy/nmdc-documentation/src/_static/js/index.js
@@ -0,0 +1,37 @@
+(function () {
+ /**
+ * Create a banner and mount it to the DOM as the first element inside the `body`.
+ *
+ * @param innerHTML {string} The HTML content you want the banner to contain.
+ */
+ function displayBanner(innerHTML = "") {
+ const sphinxRTDSidebarEl = document.querySelector('.wy-side-nav-search');
+ const zIndexOfSphinxRTDSidebar = sphinxRTDSidebarEl !== null ? parseInt(window.getComputedStyle(sphinxRTDSidebarEl).zIndex) : 0;
+
+ const divEl = document.createElement("div");
+ divEl.style.backgroundColor = "red";
+ divEl.style.textAlign = "center";
+ divEl.style.zIndex = `${zIndexOfSphinxRTDSidebar + 1}`;
+ divEl.style.position = "relative";
+ divEl.style.paddingBottom = "2px";
+ divEl.innerHTML = innerHTML;
+ document.body.insertBefore(divEl, document.body.firstChild);
+
+ // Now that we've mounted the banner to the DOM, get its height in pixels and give the sidebar's search area
+ // that same number of pixels of top margin; that way, the banner won't cover that element. Also, do the same
+ // thing whenever the browser's width changes, since the banner's height could change in that situation, too.
+ sphinxRTDSidebarEl.style.marginTop = window.getComputedStyle(divEl).height;
+ addEventListener("resize", () => {
+ sphinxRTDSidebarEl.style.marginTop = window.getComputedStyle(divEl).height;
+ });
+ }
+
+ // Register a callback function to run when the web page has fully loaded.
+ window.addEventListener("load", (event) => {
+ displayBanner(`
+ You are viewing legacy documentation, which may be obsolete.
+ You can access our current documentation
+ here.
+ `);
+ });
+})();
\ No newline at end of file
diff --git a/legacy/nmdc-documentation/src/conf.py b/legacy/nmdc-documentation/src/conf.py
index ef63cfc..2e9c00d 100644
--- a/legacy/nmdc-documentation/src/conf.py
+++ b/legacy/nmdc-documentation/src/conf.py
@@ -34,7 +34,7 @@
extensions = [
'myst_parser',
'sphinx_markdown_tables',
- 'sphinx_reredirects'
+ 'sphinx_reredirects',
]
# source_suffix = '.rst'
@@ -68,6 +68,15 @@
]
html_logo = "_static/images/nmdc-logo-bg-white.png"
+# Reference: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_favicon
+html_favicon = "_static/images/favicon.ico"
+
+# Register a custom JavaScript script for the website to load.
+# Reference: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_js_files
+html_js_files = [
+ "js/index.js"
+]
+
# -- Redirects ------------------------------------------
# Redirect old schema documentation URLs to the schema documentation
@@ -76,4 +85,16 @@
redirects = {
"reference/metadata/xylene": "https://w3id.org/nmdc/xylene", # the latter redirects to: https://microbiomedata.github.io/nmdc-schema/xylene/
"reference/metadata/*": "https://w3id.org/nmdc/nmdc",
-}
\ No newline at end of file
+}
+
+# -- Sphinx Read The Docs Theme -------------------------
+#
+# Configure "Edit on GitHub" links.
+# Reference: https://docs.readthedocs.io/en/stable/guides/edit-source-links-sphinx.html#github
+html_context = {
+ "display_github": True,
+ "github_user": "microbiomedata",
+ "github_repo": "docs",
+ "github_version": "main",
+ "conf_py_path": "/legacy/nmdc-documentation/src/", # path to directory containing `conf.py` file
+}
diff --git a/src/home_website/dev.nginx.conf b/src/home_website/dev.nginx.conf
deleted file mode 100644
index 692917f..0000000
--- a/src/home_website/dev.nginx.conf
+++ /dev/null
@@ -1,32 +0,0 @@
-# This is an Nginx configuration file used for previewing the website locally.
-# It does two things:
-# 1. It tells Nginx to serve the home website's resources directly from the Nginx container's filesystem.
-# 2. It tells Nginx to proxy other HTTP requests to the containers that serve the requested resources.
-
-events {}
-
-http {
- server {
- listen 80;
-
- # Legacy NMDC documentation.
- location /legacy/ {
- proxy_pass http://legacy-nmdc-documentation:8000/;
- }
-
- # Runtime documentation.
- location /runtime/ {
- proxy_pass http://runtime-documentation:8000/;
- }
-
- # Workflow documentation.
- location /workflows/ {
- proxy_pass http://workflow-documentation:8000/;
- }
-
- # Current NMDC documentation.
- location / {
- proxy_pass http://nmdc-documentation:8000/;
- }
- }
-}
diff --git a/src/ingesters/README.md b/src/ingesters/README.md
new file mode 100644
index 0000000..24ef2fa
--- /dev/null
+++ b/src/ingesters/README.md
@@ -0,0 +1,11 @@
+# Ingesters
+
+## Overview
+
+This directory contains code related to pulling (i.e. ingesting) source files from upstream Git repositories
+**and compiling** them into web-based documentation. In that sense, the name "ingesters" doesn't quite account
+for everything that's going on here.
+
+In addition to containing code related to ingestion, the `workflow_docs` directory also contains some documentation
+content source files, which the workflow documentation ingester combines those content source files with the ones it
+pulls from the upstream repositories, to produce a single Sphinx website about workflows.
diff --git a/src/runtime_docs/Dockerfile b/src/ingesters/runtime_docs/Dockerfile
similarity index 100%
rename from src/runtime_docs/Dockerfile
rename to src/ingesters/runtime_docs/Dockerfile
diff --git a/src/ingesters/runtime_docs/README.md b/src/ingesters/runtime_docs/README.md
new file mode 100644
index 0000000..6c631eb
--- /dev/null
+++ b/src/ingesters/runtime_docs/README.md
@@ -0,0 +1,6 @@
+# Runtime documentation ingester
+
+## Overview
+
+The `Dockerfile` in this directory is only used for local development.
+For production, we use GitHub Actions workflow file instead of a `Dockerfile`.
diff --git a/src/workflow_docs/Dockerfile b/src/ingesters/workflow_docs/Dockerfile
similarity index 100%
rename from src/workflow_docs/Dockerfile
rename to src/ingesters/workflow_docs/Dockerfile
diff --git a/src/ingesters/workflow_docs/README.md b/src/ingesters/workflow_docs/README.md
new file mode 100644
index 0000000..dd81d84
--- /dev/null
+++ b/src/ingesters/workflow_docs/README.md
@@ -0,0 +1,7 @@
+# Workflow documentation ingester
+
+## Overview
+
+The files in this directory are used for both local development and production;
+except the `Dockerfile`, which is only used for local development. For production,
+we use GitHub Actions workflow file instead of a `Dockerfile`.
diff --git a/src/workflow_docs/conf.py b/src/ingesters/workflow_docs/conf.py
similarity index 100%
rename from src/workflow_docs/conf.py
rename to src/ingesters/workflow_docs/conf.py
diff --git a/src/workflow_docs/fetch_docs_sources.sh b/src/ingesters/workflow_docs/fetch_docs_sources.sh
similarity index 100%
rename from src/workflow_docs/fetch_docs_sources.sh
rename to src/ingesters/workflow_docs/fetch_docs_sources.sh
diff --git a/src/workflow_docs/index.rst b/src/ingesters/workflow_docs/index.rst
similarity index 100%
rename from src/workflow_docs/index.rst
rename to src/ingesters/workflow_docs/index.rst
diff --git a/src/workflow_docs/metagenome_workflow_overview/docs/index.rst b/src/ingesters/workflow_docs/metagenome_workflow_overview/docs/index.rst
similarity index 100%
rename from src/workflow_docs/metagenome_workflow_overview/docs/index.rst
rename to src/ingesters/workflow_docs/metagenome_workflow_overview/docs/index.rst
diff --git a/src/workflow_docs/metagenome_workflow_overview/docs/metag_workflow2024.png b/src/ingesters/workflow_docs/metagenome_workflow_overview/docs/metag_workflow2024.png
similarity index 100%
rename from src/workflow_docs/metagenome_workflow_overview/docs/metag_workflow2024.png
rename to src/ingesters/workflow_docs/metagenome_workflow_overview/docs/metag_workflow2024.png
diff --git a/src/workflow_docs/metagenome_workflow_overview/docs/metag_workflow2024.svg b/src/ingesters/workflow_docs/metagenome_workflow_overview/docs/metag_workflow2024.svg
similarity index 100%
rename from src/workflow_docs/metagenome_workflow_overview/docs/metag_workflow2024.svg
rename to src/ingesters/workflow_docs/metagenome_workflow_overview/docs/metag_workflow2024.svg
diff --git a/src/workflow_docs/overview.rst b/src/ingesters/workflow_docs/overview.rst
similarity index 100%
rename from src/workflow_docs/overview.rst
rename to src/ingesters/workflow_docs/overview.rst