{"id":21854722,"url":"https://github.com/microbiomedata/docs","last_synced_at":"2025-03-21T19:14:40.932Z","repository":{"id":258155554,"uuid":"849070736","full_name":"microbiomedata/docs","owner":"microbiomedata","description":"User-facing, web-based documentation about the NMDC","archived":false,"fork":false,"pushed_at":"2025-03-19T19:33:25.000Z","size":66257,"stargazers_count":1,"open_issues_count":19,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-19T19:35:27.788Z","etag":null,"topics":["documentation","mkdocs","sphinx"],"latest_commit_sha":null,"homepage":"http://docs.microbiomedata.org/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/microbiomedata.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-28T23:27:25.000Z","updated_at":"2025-03-04T22:48:34.000Z","dependencies_parsed_at":"2024-10-17T21:33:24.773Z","dependency_job_id":"9f23e5a1-0592-4435-9c60-97b04d59fc20","html_url":"https://github.com/microbiomedata/docs","commit_stats":null,"previous_names":["microbiomedata/docs"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbiomedata%2Fdocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbiomedata%2Fdocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbiomedata%2Fdocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbiomedata%2Fdocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microbiomedata","download_url":"https://codeload.github.com/microbiomedata/docs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244852681,"owners_count":20521159,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","mkdocs","sphinx"],"created_at":"2024-11-28T02:10:36.457Z","updated_at":"2025-03-21T19:14:40.923Z","avatar_url":"https://github.com/microbiomedata.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Docs\n\n## Introduction\n\nThis repository underlies the NMDC [documentation website](https://docs.microbiomedata.org).\n\nThe NMDC documentation website is made up of three sections: Home, Runtime, and Workflows. The content for some of those\nsections resides in this repository, while the content for others of those sections resides in other repositories.\nThe NMDC documentation website is generated by pulling in the remote content, compiling each section on its own,\nand then merging all the compiled sections into a single website.\n\n```mermaid\nflowchart TD\n    home(\"Home\")\n    runtime(\"Runtime\")\n    workflows(\"Workflows\")\n\n    home --\u003e runtime\n    home --\u003e workflows\n```\n\n## Table of contents\n\n\u003c!-- TOC --\u003e\n* [Docs](#docs)\n  * [Introduction](#introduction)\n  * [Table of contents](#table-of-contents)\n  * [Repository structure](#repository-structure)\n  * [Content Editor Quick Reference ✍️](#content-editor-quick-reference-%EF%B8%8F)\n  * [The Home section](#the-home-section)\n    * [Making changes](#making-changes)\n      * [Basic workflow (to edit 1 file)](#basic-workflow-to-edit-1-file)\n      * [Intermediate workflow (to edit 1+ files)](#intermediate-workflow-to-edit-1-files)\n  * [Developer documentation](#developer-documentation)\n\u003c!-- TOC --\u003e\n\n## Repository structure\n\nThe repository has the following top-level directories:\n\n- `.docker/` - this directory contains files only used in the Docker-based development environment\n- `.github/` - this directory contains GitHub Actions workflow specifications\n- `content/` - this directory contains the source files for the Home section of the website\n- `pullers/` - this directory contains files related to pulling and compiling remote content into the website\n\nSome of those top-level directories have their own `README.md` files, which further describes the directory's contents.\n\n## Content Editor Quick Reference ✍️\n\nHere is a table showing the locations of files you can edit in order to make changes to a given section of the website:\n\n| To edit content in\u003cbr\u003ethis section... | Edit files in\u003cbr\u003ethis folder...                                                                               |\n|---------------------------------------|---------------------------------------------------------------------------------------------------------------|\n| Home                                  | The `content/home` folder in this repo                                                                        |\n| Runtime                               | The `docs` folder in [the `nmdc-runtime` repo](https://github.com/microbiomedata/nmdc-runtime/tree/main/docs) |\n| Workflows › Overview                  | The `pullers/workflow_docs` folder in this repo                                                               |\n| Workflows › Index                     | The `pullers/workflow_docs` folder in this repo                                                               |\n| Workflows › Chapter 1                 | The `pullers/workflow_docs/metagenome_workflow_overview` folder in this repo                                  |\n| Workflows (Other)                     | The `docs` folder in [the respective workflow's repo](https://github.com/orgs/microbiomedata/repositories)    |\n\n\u003e **Note:** As an alternative to using the table above, you can click on the \"Edit on GitHub\" links\n\u003e throughout the website.\n\nHere is a diagram showing the repositories (bottom) each section of the website (top) gets its content from.\n\n```mermaid\nflowchart BT\n    docs_repo[(\"docs\u003cbr\u003erepo\")]\n    home_section(\"Home\")\n    docs_repo --\u003e home_section\n    \n    runtime_section(\"Runtime\")\n    runtime_repo[(\"nmdc-runtime\u003cbr\u003erepo\")]\n    runtime_repo --\u003e runtime_section\n    \n    workflows_section(\"Workflows\")\n    ReadsQC_repo[(\"ReadsQC\u003cbr\u003erepo\")]\n    ReadbasedAnalysis_repo[(\"ReadbasedAnalysis\u003cbr\u003erepo\")]\n    metaAssembly_repo[(\"metaAssembly\u003cbr\u003erepo\")]\n    mg_annotation_repo[(\"mg_annotation\u003cbr\u003erepo\")]\n    metaMAGs_repo[(\"metaMAGs\u003cbr\u003erepo\")]\n    metaT_repo[(\"metaT\u003cbr\u003erepo\")]\n    metaT_ReadsQC_repo[(\"metaT_ReadsQC\u003cbr\u003erepo\")]\n    metaT_Assembly_repo[(\"metaT_Assembly\u003cbr\u003erepo\")]\n    metaT_ReadCounts_repo[(\"metaT_ReadCounts\u003cbr\u003erepo\")]\n    metaPro_repo[(\"metaPro\u003cbr\u003erepo\")]\n    metaMS_repo[(\"metaMS\u003cbr\u003erepo\")]\n    enviroMS_repo[(\"enviroMS\u003cbr\u003erepo\")]\n    docs_repo --\u003e workflows_section\n    ReadsQC_repo --\u003e workflows_section\n    ReadbasedAnalysis_repo --\u003e workflows_section\n    metaAssembly_repo --\u003e workflows_section\n    mg_annotation_repo --\u003e workflows_section\n    metaMAGs_repo --\u003e workflows_section\n    metaT_repo --\u003e workflows_section\n    metaT_ReadsQC_repo --\u003e workflows_section\n    metaT_Assembly_repo --\u003e workflows_section\n    metaT_ReadCounts_repo --\u003e workflows_section\n    metaPro_repo --\u003e workflows_section\n    metaMS_repo --\u003e workflows_section\n    enviroMS_repo --\u003e workflows_section\n```\n\nThe website will automatically be regenerated and redeployed whenever a new commit is made on—or merged into—the `main`\nbranch of _this_ repository. Regeneration includes pulling content from the remote repositories. The regeneration and redeployment process usually takes about three minutes to complete.\n\n## The Home section\n\nThe `content/home/` directory contains the source files for the Home section of the website. That directory began as an\nalmost 1-to-1 copy of the `NMDC_documentation` repository. More information about what was—and wasn't—copied is\navailable [here](./content/home/README.md).\nThis section of the website is generated using [Sphinx](https://www.sphinx-doc.org), a static site generator.\nIts content is organized according to the [Diátaxis](https://diataxis.fr/how-to-use-diataxis/#use-diataxis-as-a-guide-not-a-plan) guidelines.\n\n### Making changes\n\nHere's how you can make (technically, \"propose\") a change to this section of the website:\n\n**Note:** The high-level process may be familiar to you: (1) create a GitHub Issue, (2) create a branch associated\nwith that Issue, (3) make changes on that branch, and (4) create a Pull Request to merge that branch into `main`.\n\n```mermaid\nflowchart LR\n    a(\"1: Create issue\")\n    b(\"2: Create branch\")\n    c(\"3: Make changes on branch\")\n    d(\"4: Create pull request\")\n\n    a --\u003e b --\u003e c --\u003e d\n```\n\nYou can use whatever workflow you want in order to do those things. The following are some example workflows we've\ndocumented for our teammates.\n\n#### Basic workflow (to edit 1 file)\n\n\u003cdetails\u003e\n  \u003csummary\u003eShow/hide steps\u003c/summary\u003e\n\n1. Create a GitHub Issue describing the issue you want to address (e.g. \"`Link is broken`\")\n2. On GitHub, go to the file within `content/home/src` that you want to edit\n3. Click the \"Edit this file\" button (i.e. the pencil icon button) at the upper right\n4. Edit the file, making the changes you want to make\n5. Click the \"Commit changes...\" button at the upper right\n6. Customize the commit message to tell others what you did (e.g. \"`Fix typo in link`\")\n7. Mark the bubble that says \"**Create a new branch** for this commit and start a pull request\"\n8. (Recommended) Customize the branch name so it starts with the GitHub Issue number (e.g. `123-link-is-broken`)\n9. Click \"Propose changes\"\n10. Fill in the Pull Request form and click \"Create pull request\"\n\n\u003c/details\u003e\n\nYou will end up with a Pull Request (PR) containing the changes. Once the PR gets merged into `main`,\nthe documentation website will automatically be updated to reflect the changes you made.\n\n#### Intermediate workflow (to edit 1+ files)\n\n\u003cdetails\u003e\n  \u003csummary\u003eShow/hide steps\u003c/summary\u003e\n\n1. Create a GitHub Issue describing the issue you want to address (e.g. \"`Link is broken`\")\n2. Visit https://github.dev/microbiomedata/docs/\n3. Click the branch name (e.g. `main`) at the lower left\n4. Click \"Create a new branch...\" at the top\n5. Enter a name for the branch, beginning with an issue number (e.g. `123-link-is-broken`)\n6. (If prompted) Click \"Switch to Branch\"\n7. Make changes in `content/home/src`\n8. Click the \"Source Control\" icon in the left sidebar (3rd from the top)\n9. Hover over the \"Changes\" heading and click the `+` icon that appears\n10. Enter a commit message to tell others what you did (e.g. \"`Fix typo in link`\")\n11. Click the \"Commit \u0026 Push\" button\n12. Visit https://github.com/microbiomedata/docs/ and create a Pull Request for that branch\n\n\u003c/details\u003e\n\nYou will end up with a Pull Request (PR) containing the changes. Once the PR gets merged into `main`,\nthe documentation website will automatically be updated to reflect the changes you made.\n\n## Developer documentation\n\nDeveloper documentation is in [development.md](./development.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrobiomedata%2Fdocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrobiomedata%2Fdocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrobiomedata%2Fdocs/lists"}