[!NOTE]
This repository is in early development. We are currently in the process of reviewing, pruning, and consolidating our documentation.
This repository contains the content that we compile into our documentation website.
This repository has the following sections:
./content
: Current, high-level content about NMDC
nmdc
: Current content (under construction), initialized as a copy of the legacy content./legacy
: Legacy content we include in the website to support legacy references/publications./src
: Code we use to compile local and remote content into a website./
: Repository-level configuration files and documentationThe ./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.
This documentation is implemented within the Sphinx framework. The content is organized according to the Diátaxis 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:
./content/nmdc/src
that you want to editFix typo in link
")123-fix-foo-in-bar
)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.
main
) at the lower left123-fix-foo-in-bar
)./content/nmdc/src
+
icon that appearsFix typo in link
")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.
Most of the files in the legacy/nmdc-documentation
directory are files that we copied from
commit 8786ff5a
in the NMDC_documentation repository.
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
.
When copying the aforementioned files from the NMDC_documentation
repository, we omitted the following files:
docs/reference/metadata
docs/_static/images/reference/metadata
docs/_static/jsonschema
Instead of maintaining a local copy of that documentation here, we redirect visitors to the standalone schema documentation.
Example: When someone visits
/reference/metadata/xylene.html
on this documentation website, they'll be automatically redirected to https://microbiomedata.github.io/nmdc-schema/xylene/. This redirection is configured inlegacy/nmdc-documentation/src/conf.py
.
You can compare the legacy/nmdc-documentation/src
directory with the corresponding directory in the
upstream repository, by following these steps:
# Clone the upstream repository onto your computer.
git clone https://github.com/microbiomedata/NMDC_documentation.git /tmp/NMDC_documentation
# Use Git to compare the corresponding directories.
git diff --stat /tmp/NMDC_documentation/docs ./legacy/nmdc-documentation/src
[!NOTE]
TODO
.github/workflows
: GitHub Actions workflowsdocker-compose.yml
: Specification for a set of container images you can use when editing any section of our documentation websiteREADME.md
: This documentThe .github/workflows
directory contains YAML files that we use to configure GitHub Actions.
We use GitHub Actions to (a) compile local and remote content into a website,
and to (b) publish that website to the Internet.
Assuming you have Docker installed, you can spin up the development environment by running:
docker compose up
That will start up several Docker containers, which you can access via the URLs below:
In addition, whenever you make changes to content, 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).
requirements.txt
files to indicate specific versions.rst
files into Markdown (.md
)