Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make nmdc_overview.rst be the landing page of the website #122

Open
eecavanna opened this issue Dec 24, 2024 · 2 comments
Open

Make nmdc_overview.rst be the landing page of the website #122

eecavanna opened this issue Dec 24, 2024 · 2 comments
Assignees
Labels
x small less than 1 day

Comments

@eecavanna
Copy link
Collaborator

The creation of this ticket was prompted by this comment: #121 (comment)

File path: content/home/src/overview/nmdc_overview.rst

Some options:

  1. Use a redirect to redirect visitors from / to /overview/nmdc_overview.html
  2. Configure Sphinx to show the content of /overview/nmdc_overview.html on the home page

I know how to do option 1 already. I don't know how to do option 2.

Regarding option 2, I do see that there is a Sphinx option called "master_doc" (a.k.a. "root_doc"): https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-root_doc. Looks like that is where Sphinx will get the ToC from. Maybe Sphinx would also get the homepage content form that file (?).

@eecavanna
Copy link
Collaborator Author

eecavanna commented Dec 24, 2024

Regarding option 1: This redirect (in conf.py) works:

 redirects = {
+    "index.html": "/overview/nmdc_overview.html",
     "runtime.html": "/runtime/",

One consequence of this is that (in general) the sidebar "scrolls down" to the active page. If this page is our landing page, the sidebar on our landing page will be "scrolled down."

image

If stakeholders are OK with that, we can proceed with this solution.

@eecavanna
Copy link
Collaborator Author

eecavanna commented Dec 24, 2024

Here's a diff showing the changes I made when implementing option 2.

Basically, adding :hidden: (docs) to the TOC sections makes it so that section of links does not appear in the content area of that web page. I added it to all TOC sections, which effectively blanked out the home page (except for the header).

To remove the header (i.e. "NMDC Documentation"), I deleted those header lines from the RST file.

Next, to get the overview content to appear on the page, I copy/pasted it into the RST file.

Finally, in content/home/src/, I deleted the now-redundant overview/nmdc_overview.rst file (and, indeed, the containing overview directory, which was now empty); then, I deleted the obsolete "NMDC Overview" section from the TOC.

diff --git a/content/home/src/index.rst b/content/home/src/index.rst
index 7f40dc0..3d67e85 100755
--- a/content/home/src/index.rst
+++ b/content/home/src/index.rst
@@ -1,16 +1,7 @@
-
-NMDC Documentation
-==================
-
-.. toctree::
-   :maxdepth: 2
-   :caption: NMDC Overview:
-
-   overview/nmdc_overview.rst
-
 .. toctree::
    :maxdepth: 2
    :caption: Tutorials:
+   :hidden:
  
    Submitting to NMDC <./tutorials/submission_portal.md>
    Running the Workflows <./tutorials/run_workflows>
@@ -19,6 +10,7 @@ NMDC Documentation
 .. toctree::
    :maxdepth: 2
    :caption: How-To Guides:
+   :hidden:
 
    Creating a Data Mgt. Plan <./howto_guides/data_plan.md>
    Submitting to NMDC <./howto_guides/submit2nmdc.md>
@@ -30,6 +22,7 @@ NMDC Documentation
 .. toctree::
    :maxdepth: 2
    :caption: Reference:
+   :hidden:
 
    NMDC Schema <https://w3id.org/nmdc/about>
    NMDC Runtime <runtime.rst>
@@ -39,6 +32,29 @@ NMDC Documentation
 .. toctree::
    :maxdepth: 2
    :caption: Explanation:
+   :hidden:
 
    FAIR Data <./explanation/fair_data.md>
    Community Conversations <./explanation/community_conversations.md>
+
+Advancing microbiome science together: Welcome to the NMDC
+==================
+
+We have built the National Microbiome Data Collaborative (NMDC) to advance how scientists create, use, and reuse data to redefine the way we understand and harness the power of microbes. The core infrastructure elements of the NMDC are: (1) the `Submission Portal <https://data.microbiomedata.org/submission/home>`_ to support collection of standardized study and biosample information; (2) `Field Notes <https://microbiomedata.org/field-notes/>`_, a mobile app to streamline real-time metadata and field measurement collection; (3) `NMDC EDGE <https://nmdc-edge.org/home>`_, an intuitive user interface to access standardized bioinformatics workflows; and (4) the `Data Portal <https://data.microbiomedata.org/>`_ and `API <https://api.microbiomedata.org/docs>`_, resources for consistently processed and integrated multi-omics data enabling search, access, and download. Our engagement strategy includes partnerships with complementary data resources like DOE’s Environmental Systems Science Data Infrastructure for a Virtual Ecosystem (`ESS-DIVE <https://ess-dive.lbl.gov>`_) and DOE’s Systems Biology Knowledgebase (`KBase <https://www.kbase.us>`_); partnerships with DOE User Facilities, the Joint Genome Institute (`JGI <https://jgi.doe.gov>`_) and the Envionmental Molecular Sciences Laboratory (`EMSL <https://www.emsl.pnnl.gov>`_); coordinating with interagency programs outside of the DOE ecosystem such as NSF’s National Ecological Observatory Network (`NEON <https://www.neonscience.org>`_);  and development of our flagship engagement programs, the NMDC `Ambassadors <https://microbiomedata.org/ambassadors>`_ and `Champions <https://microbiomedata.org/community/championsprogram>`_. This community-centric framework leverages unique capabilities, expertise, and resources available at the Department of Energy National Laboratories to create an enabling environment for findable, accessible, interoperable, and reusable (FAIR) multi-omics microbiome data.
+
+
+
+About our Documentation
+==================
+
+To support a systematic approach to our technical documentation, we have adopted the `Diátaxis framework <https://diataxis.fr/>` which identifies four distinct forms of documentation: tutorials, how-to guides, technical reference, and explanation. We aim for our documentation to be accessible to a broad audience, so whether you are new to microbiome research or a leading scientist in the field, we welcome everyone to learn more from our:
+
+1. Tutorials (Learning-oriented): get started through short, hands-on activities
+2. How-To Guides (Task-oriented): step-by-step instructions for using NMDC's products and resources
+3. Explanation (Understanding-oriented): background information covering a wide range of topics
+4. Reference (Information-oriented): in-depth learning materials
+
+Let us know if you have suggestions to further support your research by `reaching out to us <https://microbiomedata.org/contact>`_!
+
+.. image:: ../_static/images/overview/diataxis_documentation_graphic.png
+   :width: 1000

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
x small less than 1 day
Development

No branches or pull requests

1 participant