Merge pull request #40 from microbiomedata/39c-copy-legacy-docs-to-no…

…n-legacy-place

Duplicate legacy documentation as foundation for future documentation

.github/workflows/compile-current-nmdc-documentation.yml

@@ -0,0 +1,44 @@
+# This GitHub Actions workflow compiles the Sphinx documentation into web-based documentation.
+# Reference: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions
+name: Compile current NMDC documentation into HTML
+
+on:
+  push: { branches: [ main ] }
+  workflow_dispatch: { }
+  # Allow this workflow to be called by other workflows.
+  # Reference: https://docs.github.com/en/actions/using-workflows/reusing-workflows
+  workflow_call: { }
+
+jobs:
+  compile:
+    name: Compile
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        # Set a default working directory for all `run` steps in this job.
+        # Reference: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_iddefaultsrun
+        working-directory: content/nmdc
+    permissions:
+      contents: read
+    steps:
+      - name: Check out commit  # Docs: https://github.com/actions/checkout
+        uses: actions/checkout@v4
+      - name: Set up Python  # Docs: https://github.com/actions/setup-python
+        uses: actions/setup-python@v5
+        with: { python-version: '3.12' }
+      - name: Install Sphinx  # Docs: https://pypi.org/project/Sphinx/
+        run: pip install Sphinx
+      - name: Install other dependencies
+        run: pip install -r requirements.txt
+      - name: Compile source documents into HTML
+        run: sphinx-build -b html src ${{ github.workspace }}/content/nmdc/_build/html
+        # Upload the result as an "artifact" so it can then be downloaded and used by another job.
+      - name: Save the HTML for publishing later  # Docs: https://github.com/actions/upload-artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: current-nmdc-documentation-as-html
+          # Note: Relative `path` values here are relative to the _workspace_, not to the current working directory.
+          #       Reference: https://github.com/actions/upload-artifact/pull/477#issue-2044900649
+          path: content/nmdc/_build/html
+          if-no-files-found: error
+          retention-days: 1  # Note: 1 day is the shortest period possible

.github/workflows/deploy-to-gh-pages.yml

@@ -17,6 +17,9 @@ jobs:
   compile-legacy-nmdc-documentation:
     name: Compile legacy NMDC documentation
     uses: ./.github/workflows/compile-legacy-nmdc-documentation.yml
+  compile-current-nmdc-documentation:
+    name: Compile current NMDC documentation
+    uses: ./.github/workflows/compile-current-nmdc-documentation.yml
   fetch-and-compile-nmdc-runtime-documentation:
     name: Fetch and compile NMDC Runtime documentation
     uses: ./.github/workflows/fetch-and-compile-nmdc-runtime-documentation.yml
@@ -30,6 +33,7 @@ jobs:
     # Reference: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idneeds
     needs:
       - compile-legacy-nmdc-documentation
+      - compile-current-nmdc-documentation
       - fetch-and-compile-nmdc-runtime-documentation
       - fetch-and-compile-mag-workflow-documentation
     runs-on: ubuntu-latest
@@ -47,6 +51,7 @@ jobs:
           ls -R artifacts
           mkdir -p _build/html _build/html/legacy _build/html/workflows
           cp -R artifacts/legacy-nmdc-documentation-as-html _build/html/legacy/nmdc-documentation
+          cp -R artifacts/current-nmdc-documentation-as-html _build/html/nmdc
           cp -R artifacts/nmdc-runtime-documentation-as-html _build/html/nmdc-runtime-documentation
           cp -R artifacts/mag-workflow-documentation-as-html _build/html/workflows/mag-workflow-documentation
           cp -R content/assets _build/html/assets

README.md

@@ -17,13 +17,12 @@ This repository contains the content that we compile into our
   * [Table of contents](#table-of-contents)
   * [Repository structure](#repository-structure)
     * [Content](#content)
+      * [Maintenance](#maintenance)
+        * [Procedure: Basic (to edit 1 file)](#procedure-basic-to-edit-1-file)
+        * [Procedure: Intermediate (to edit 1+ files)](#procedure-intermediate-to-edit-1-files)
     * [Legacy content](#legacy-content)
       * [NMDC documentation](#nmdc-documentation)
         * [Omissions](#omissions)
-        * [Maintenance](#maintenance)
-          * [Prerequisites](#prerequisites)
-          * [Procedure: Basic (to edit 1 file)](#procedure-basic-to-edit-1-file)
-          * [Procedure: Intermediate (to edit 1+ files)](#procedure-intermediate-to-edit-1-files)
     * [Code](#code)
     * [Repository-level configuration files and documentation](#repository-level-configuration-files-and-documentation)
       * [GitHub Actions](#github-actions)
@@ -37,14 +36,65 @@ This repository contains the content that we compile into our
 This repository has the following sections:
 
 1. `./content`: Current, high-level content about NMDC
+   1. `nmdc`: Current content (under construction), initialized as a copy of the legacy content
 2. `./legacy`: Legacy content we include in the website to support legacy references/publications
 3. `./src`: Code we use to compile local and remote content into a website
 4. `./`: Repository-level configuration files and documentation
 
 ### Content
 
-> [!NOTE]  
-> TODO
+The `./content/nmdc` directory contains our current documentation that is not pulled from an external repository.
+This directory began as a 1-to-1 copy of the `./legacy/nmdc-documentation` directory. The latter is, itself, mostly a
+copy of the `NMDC_documentation` repository (more details about this are in the "Legacy content" section below).
+
+Unlike the contents of the `./legacy/nmdc-documentation` directory, the contents of the `./content/nmdc` directory will
+continue to change over time; i.e. NMDC team members will update and add documentation to this directory.
+
+#### Maintenance
+
+This documentation is implemented within the [Sphinx](https://www.sphinx-doc.org) framework.
+The content is organized according to the
+[Diátaxis](https://diataxis.fr/how-to-use-diataxis/#use-diataxis-as-a-guide-not-a-plan) guidelines.
+
+Here's how you can make (technically, "propose") changes to this documentation:
+
+> **Note:** The high-level process may be familiar to you: (1) create a GitHub Issue, (2) create a branch associated
+> with that Issue, (3) make changes on that branch, and (4) create a Pull Request to merge that branch into `main`.
+> You can use whatever workflow you want in order to follow that process. The following are some example workflows:
+
+##### Procedure: Basic (to edit 1 file)
+
+1. Create a GitHub Issue describing what you want to change (e.g. "Fix Foo in Bar")
+2. On GitHub, go to the file within `./content/nmdc/src` that you want to edit
+3. Click the "Edit this file" button (i.e. the pencil icon button) at the upper right
+4. Edit the file
+5. Click the "Commit changes..." button at the upper right
+6. Customize the commit message to tell others what you did (e.g. "`Fix typo in link`")
+7. Mark the bubble that says "**Create a new branch** for this commit and start a pull request"
+8. (Recommended) Customize the branch name so it starts with the GitHub Issue number (e.g. `123-fix-foo-in-bar`)
+9. Click "Propose changes"
+10. Fill in the Pull Request form and click "Create pull request"
+
+You will end up with a Pull Request (PR) containing the changes. Once the PR gets merged into `main`,
+the documentation website will automatically be updated to reflect the changes.
+
+##### Procedure: Intermediate (to edit 1+ files)
+
+1. Create a GitHub Issue describing what you want to change (e.g. "Fix Foo in Bar")
+2. Visit https://github.dev/microbiomedata/docs/
+3. Click the branch name (e.g. `main`) at the lower left
+4. Click "Create a new branch..." at the top
+5. Enter a name for the branch, beginning with an issue number (e.g. `123-fix-foo-in-bar`)
+6. (If prompted) Click "Switch to Branch"
+7. Make changes in `./content/nmdc/src`
+8. Click the "Source Control" icon in the left sidebar (3rd from the top)
+9. Hover over the "Changes" heading and click the `+` icon that appears
+10. Enter a commit message to tell others what you did (e.g. "`Fix typo in link`")
+11. Click the "Commit & Push" button
+12. Visit https://github.com/microbiomedata/docs/ and create a Pull Request for that branch
+
+You will end up with a Pull Request (PR) containing the changes. Once the PR gets merged into `main`,
+the documentation website will automatically be updated to reflect the changes.
 
 ### Legacy content
 
@@ -58,7 +108,6 @@ That was the latest commit on the `main` branch as of August 28, 2024.
 In addition to the files we copied, the directory also contains some files that are _exclusive_ to this repository;
 e.g., `Dockerfile` and `.gitignore`.
 
-
 ##### Omissions
 
 When copying the aforementioned files from the `NMDC_documentation` repository, we _omitted_ the following files:
@@ -85,53 +134,6 @@ git clone https://github.com/microbiomedata/NMDC_documentation.git /tmp/NMDC_doc
 git diff --stat /tmp/NMDC_documentation/docs ./legacy/nmdc-documentation/src
 ```
 
-##### Maintenance
-
-This documentation is implemented within the [Sphinx](https://www.sphinx-doc.org) framework.
-The content is organized according to the [Diátaxis](https://diataxis.fr/how-to-use-diataxis/#use-diataxis-as-a-guide-not-a-plan) guidelines.
-
-Here's how you can propose changes to this documentation:
-
-> Note: The general flow is: (1) create a GitHub Issue, (2) create a branch associated with that Issue,
-> (3) make changes on that branch, and (4) create a Pull Request to merge that branch into the `main` branch.
-> The following are a couple of the many ways someone can do those things (other ways are also OK).
-
-###### Prerequisites
-
-1. Create a GitHub Issue describing what you want to change (e.g. "Fix Foo in Bar")
-
-###### Procedure: Basic (to edit 1 file)
-
-1. On GitHub, go to the file within `legacy/nmdc-documentation/src/` that you want to edit
-2. Click the "Edit this file" button (i.e. the pencil icon button) at the upper right
-3. Edit the file
-4. Click the "Commit changes..." button at the upper right
-5. Customize the commit message to tell others what you did (e.g. "`Fix typo in link`")
-6. Mark the bubble that says "**Create a new branch** for this commit and start a pull request"
-7. (Recommended) Customize the branch name so it starts with the GitHub Issue number (e.g. `123-fix-foo-in-bar`)
-8. Click "Propose changes"
-9. Fill in the Pull Request form and click "Create pull request"
-
-You will end up with a Pull Request (PR) containing the changes. Once the PR gets merged into `main`,
-the documentation website will automatically be updated to reflect the changes.
-
-###### Procedure: Intermediate (to edit 1+ files)
-
-1. Visit https://github.dev/microbiomedata/docs/
-2. Click the branch name (e.g. `main`) at the lower left
-3. Click "Create a new branch..." at the top
-4. Enter a name for the branch, beginning with an issue number (e.g. `123-fix-foo-in-bar`)
-5. (If prompted) Click "Switch to Branch"
-6. Make changes in `legacy/nmdc-documentation/src`
-7. Click the "Source Control" icon in the left sidebar (3rd from the top)
-8. Hover over the "Changes" heading and click the `+` icon that appears
-9. Enter a commit message to tell others what you did (e.g. "`Fix typo in link`")
-10. Click the "Commit & Push" button
-11. Visit https://github.com/microbiomedata/docs/ and create a Pull Request for that branch
-
-You will end up with a Pull Request (PR) containing the changes. Once the PR gets merged into `main`,
-the documentation website will automatically be updated to reflect the changes. 
-
 ### Code
 
 > [!NOTE]  
@@ -159,13 +161,15 @@ Assuming you have Docker installed, you can spin up the development environment
 docker compose up
 ```
 
-That will run a web server, serving the legacy section of the website at the following URL:
+That will start up several Docker containers, which you can access via the URLs below:
 
-- http://localhost:50000
+- http://localhost:5000 - the home page of the centralized documentation website
+- http://localhost:5001 - the legacy documentation website
+- http://localhost:5002 - the current documentation website
 
 In addition, whenever you make changes to content,
-the associated sections of the website will automatically be rebuilt
-(at which point, you can refresh your web browser to see the newly-rebuilt sections).
+the associated section of the associated website will automatically be rebuilt
+(at which point, you can refresh your web browser to see the newly-rebuilt section).
 
 # TODO
 

content/index.html

@@ -98,12 +98,17 @@ <h4 class="card-title h5">Running bioinformatics workflows</h4>
                     <div class="card-body">
                         <h4 class="card-title h5">Other stuff</h4>
                         <p class="card-text">
-                            Explore documentation produced during earlier phases of the project.
+                            Read tutorials, how-to guides, references, and explanations of various aspects of the NMDC.
                         </p>
                         <ul class="list-group">
+                            <li class="list-group-item">
+                                <a href="nmdc/index.html">
+                                    General documentation
+                                </a>
+                            </li>
                             <li class="list-group-item">
                                 <a href="legacy/nmdc-documentation/index.html">
-                                    Legacy documentation
+                                    Legacy platform documentation
                                 </a>
                             </li>
                         </ul>

content/nmdc/.gitignore

@@ -0,0 +1,2 @@
+# Ignore the web-based documentation generated by Sphinx.
+/_build

content/nmdc/Dockerfile

@@ -0,0 +1,21 @@
+# Base this container image upon the official Python container image.
+# Reference: https://hub.docker.com/_/python
+FROM python:3.12
+
+WORKDIR /app
+
+# Install a package that can be used to effectively run Spinx in "watch" mode,
+# wherein the web-based documentation will automatically be rebuilt whenever
+# a source file changes.
+# Reference: https://github.com/sphinx-doc/sphinx-autobuild
+RUN pip3 install sphinx-autobuild
+
+ADD requirements.txt .
+RUN pip3 install -r requirements.txt
+
+EXPOSE 8000
+
+# Run `sphinx-autobuild` in a way that, whenever something changes
+# in the `src` directory, it rebuilds the web-based documentation
+# and stores the result in `_build/html`.
+CMD ["sphinx-autobuild", "--host", "0.0.0.0", "src", "_build/html"]

content/nmdc/requirements.txt

@@ -0,0 +1,7 @@
+myst-parser
+sphinx_markdown_tables
+sphinx_rtd_theme
+
+# Sphinx plugin that handles redirects.
+# Reference: https://pypi.org/project/sphinx-reredirects/
+sphinx-reredirects

content/nmdc/src/_static/css/custom.css

@@ -0,0 +1,13 @@
+/* Hide "On Read the Docs" section from versions menu */
+div.rst-versions > div.rst-other-versions > div.injected > dl:nth-child(3) {
+    display: none;
+}
+/* Hide "On GitHub" section from versions menu */
+div.rst-versions > div.rst-other-versions > div.injected > dl:nth-child(4) {
+    display: none;
+}
+
+/* Customize text wrapping in table cells */
+.wy-table-responsive table td, .wy-table-responsive table th {
+    white-space: inherit;
+}

content/nmdc/src/_templates/breadcrumbs.html.disabled

@@ -0,0 +1,4 @@
+{%- extends "sphinx_rtd_theme/breadcrumbs.html" %}
+
+{% block breadcrumbs_aside %}
+{% endblock %}

content/nmdc/src/conf.py

@@ -0,0 +1,79 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+
+# sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'NMDC Documentation'
+copyright = '2024, The NMDC Team'
+author = 'The NMDC Team'
+
+# The full version, including alpha/beta/rc tags
+release = '0.1'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+   'myst_parser',
+   'sphinx_markdown_tables',
+   'sphinx_reredirects'
+]
+
+# source_suffix = '.rst'
+source_suffix = ['.rst', '.md']
+# Add any paths that contain templates here, relative to this directory.
+# templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+html_title = 'NMDC'
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+# These paths are either relative to html_static_path
+# or fully qualified paths (eg. https://...)
+html_css_files = [
+    'css/custom.css',
+]
+html_logo = "_static/images/nmdc-logo-bg-white.png"
+
+# -- Redirects ------------------------------------------
+
+# Redirect old schema documentation URLs to the schema documentation
+# that is automatically kept in sync with the schema.
+# Reference: https://pypi.org/project/sphinx-reredirects/
+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",
+}