docs: fix the issue with sidebar toc levels and people option depreca…

…tion (#7) * fix(actions): add proper branch references * docs(open science): correct sidebar toc level * docs(date): documents now show last updated date * docs(updated): deprecate use of people option .. versionadded:: 2024.09.30 [1] Added new "On this page" section which represents a quick summary of key takeaways from the whole page. .. deprecated:: 2024.09.30 [1] Deprecated the use of `people` options from the `contributors` directive as part of new change from the underlying theme. --------- Signed-off-by: Akshay Mestry <xa@mes3.dev>
ciesin-geospatial · Sep 6, 2024 · 26a0220 · 26a0220
1 parent c5988da
commit 26a0220
Show file tree

Hide file tree

Showing 9 changed files with 108 additions and 24 deletions.
diff --git a/docs/source/_documentation/getting-started.rst b/docs/source/_documentation/getting-started.rst
@@ -1,15 +1,13 @@
 .. Author: Akshay Mestry <xa@mes3.dev>
 .. Created on: Saturday, September 01 2024
-.. Last updated on: Saturday, September 01 2024
+.. Last updated on: Friday, September 06 2024
 
 ===============================================================================
 Getting Started
 ===============================================================================
 
 .. title-hero::
-    :article: Guide
     :icon: fa-solid fa-compass
-    :gradient: linear-gradient(-90deg, #f9dfef, #fdf5fa)
     :summary:
         SCHOOL program is a key initiative by NASA aimed at advancing Open
         Science principles, which emphasize transparency, collaboration, and
@@ -27,6 +25,38 @@ Getting Started
     - amunoz8@my.nl.edu
     - https://github.com/america-m/
 
+    - Akshay Mestry
+    - xa@mes3.dev
+    - https://github.com/xames3/
+
+.. dropdown:: On this page
+
+    **Objective of TOPST SCHOOL Program.** It aims to teach Open Science
+    principles through structured learning modules, covering topics like
+    environmental justice, climate change, and FAIR data principles. The
+    program is designed to be interactive, interdisciplinary, and accessible
+    to learners of all backgrounds.
+
+    **Importance of Open Science.** Open Science is crucial for making research
+    more accessible and collaborative, which is essential for addressing
+    complex global challenges such as climate change and pandemics. It
+    involves sharing all aspects of the research process to enhance
+    visibility, reproducibility, and impact.
+
+    **Curriculum Overview** The program includes various modules on topics like
+    Water Systems, Health and Air Quality, Environmental Justice, Natural
+    Disasters, Climate Change, Agriculture, and Wildfires. These modules are
+    designed to be transformative and interactive, with case studies and
+    real-world data analysis.
+
+    **Community Engagement.** The program encourages collaboration and
+    engagement with peers to enrich the learning experience and foster a
+    supportive community. Start with an introductory module or a topic of
+    interest, and participate actively in the learning community to
+    contribute to Open Science.
+
+----
+
 We're delighted to welcome you to the **Science Core Heuristics for Open
 Science Outcomes in Learning** (:term:`SCHOOL`) program, a pivotal part of
 NASA's commitment to fostering a culture of `Open Science`_. Open Science is

diff --git a/docs/source/_documentation/open-science-essentials.rst b/docs/source/_documentation/open-science-essentials.rst
@@ -1,21 +1,18 @@
 .. Author: Akshay Mestry <xa@mes3.dev>
 .. Created on: Saturday, September 01 2024
-.. Last updated on: Saturday, September 01 2024
+.. Last updated on: Friday, September 06 2024
 
 ===============================================================================
 Open Science Essentials
 ===============================================================================
 
 .. title-hero::
-    :article: Guide
     :icon: fa-solid fa-screwdriver-wrench fa-flip-horizontal
-    :gradient: linear-gradient(135deg, #ffe6d9, #fff8f3)
     :summary:
-        SCHOOL program is a key initiative by NASA aimed at advancing Open
-        Science principles, which emphasize transparency, collaboration, and
-        inclusivity in research.
+        NASA's Open Science initiative is transforming the scientific process
+        by promoting transparency, collaboration, and inclusivity.
 
-.. tags:: getting-started
+.. tags:: getting-started, what-you-need
 
 .. contributors::
 
@@ -27,8 +24,27 @@ Open Science Essentials
     - amunoz8@my.nl.edu
     - https://github.com/america-m/
 
+    - Akshay Mestry
+    - xa@mes3.dev
+    - https://github.com/xames3/
+
+.. dropdown:: On this page
+
+    **NASA's Open Science Initiative.** NASA is committed to fostering an
+    inclusive Open Science community, promoting transparency, collaboration,
+    and early sharing of data and research. This initiative, known as Open
+    Source Science, aims to make all aspects of scientific research open and
+    accessible from the start, encouraging a cultural shift in science.
+
+    **Transform to Open Science Initiative.** NASA's TOPS initiative provides
+    education and tools to help researchers and the public adopt Open Science
+    practices. The free online course "Open Science 101" offers practical
+    insights into these principles.
+
+----
+
 -------------------------------------------------------------------------------
-Overview
+Prelude
 -------------------------------------------------------------------------------
 
 :term:`NASA` is at the forefront of a transformative movement in the scientific
@@ -57,7 +73,7 @@ increasing the reliability and impact of scientific findings.
 
 .. figure:: https://science.nasa.gov/wp-content/uploads/2021/10/
     ksc-20210114-ilw02-0030large.jpg?w=2048&format=webp
-    :class: height-450 object-fit-center
+    :class: height-450 object-fit-center fade-image
 
     Researcher carefully preparing samples in a laboratory setting, embodying
     the spirit of Open Science. By sharing data transparently and including
@@ -86,7 +102,7 @@ key areas where Open Science makes a significant impact:
 
 .. figure:: https://science.nasa.gov/wp-content/uploads/2021/10/pia23275large.
     jpg?w=2048&format=webp
-    :class: height-450 object-fit-top
+    :class: height-450 object-fit-top fade-image
 
     Researchers collaborate in fieldwork, studying geological formations in a
     remote landscape. This scene reflects NASA's commitment to Open Science,

diff --git a/docs/source/_tags/contributors.rst b/docs/source/_tags/contributors.rst
@@ -0,0 +1,10 @@
+.. _sphx_tag_contributors:
+
+Tagged: contributors
+####################
+
+.. toctree::
+    :maxdepth: 1
+    :caption: With this tag
+
+    ../school-team.rst
diff --git a/docs/source/_tags/getting-started.rst b/docs/source/_tags/getting-started.rst
@@ -0,0 +1,11 @@
+.. _sphx_tag_getting-started:
+
+Tagged: getting-started
+#######################
+
+.. toctree::
+    :maxdepth: 1
+    :caption: With this tag
+
+    ../_documentation/getting-started.rst
+    ../_documentation/open-science-essentials.rst
diff --git a/docs/source/_tags/tagsindex.rst b/docs/source/_tags/tagsindex.rst
@@ -9,4 +9,6 @@ Tags overview
     :caption: Tags
     :maxdepth: 1
 
+    contributors (1) <contributors.rst>
+    getting-started (2) <getting-started.rst>
     glossary (1) <glossary.rst>
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -4,7 +4,7 @@
 
 Author: Akshay Mestry <xa@mes3.dev>
 Created on: Saturday, August 17 2024
-Last updated on: Friday, August 30 2024
+Last updated on: Thursday, September 05 2024
 
 This file contains the configuration settings for building the TOPSTSCHOOL
 documentation using Sphinx, a popular Python documentation tool. Sphinx
@@ -28,6 +28,7 @@
 
 from __future__ import annotations
 
+import subprocess
 import typing as t
 from datetime import datetime as dt
 
@@ -52,16 +53,28 @@
 intersphinx_mapping: dict[str, tuple[str, t.Any]] = {
     "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
 }
+
 rst_epilog = ""
 with open("_static/urls.txt") as f:
     rst_epilog += f.read()
 
+try:
+    last_updated_cmd = (
+        "git",
+        "log",
+        "--pretty=format:%cd",
+        "--date=format:%B %d, %Y",
+        "-n1",
+    )
+    last_updated = subprocess.check_output(last_updated_cmd).decode()
+except Exception:
+    last_updated = None
+
 # -- Project information -----------------------------------------------------
 html_coeus_author: t.Final[str] = "TOPSTSCHOOL Development Team"
 html_coeus_copyright: t.Final[str] = f"{dt.now().year}, {html_coeus_author}."
 html_coeus_email: t.Final[str] = "TOPSTSCHOOL@gmail.com"
 html_coeus_github: str = source + "/docs"
-html_coeus_include_last_updated_date: bool = True
 html_coeus_license: str = f"{source}/blob/main/LICENSE"
 html_coeus_repository: str = source
 html_coeus_title: t.Final[str] = "TOPSTSCHOOL"
@@ -73,6 +86,7 @@
 html_coeus_documentation: str = html_coeus_homepage
 html_coeus_theme_options: dict[str, t.Any] = {
     "show_previous_next_pages": True,
+    "last_updated": last_updated,
 }
 
 # -- Options for HTML output --------------------------------------------------

diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst
@@ -1,15 +1,13 @@
 .. Author: Akshay Mestry <xa@mes3.dev>
 .. Created on: Friday, August 30 2024
-.. Last updated on: Saturday, August 31 2024
+.. Last updated on: Friday, September 06 2024
 
 ===============================================================================
-Glossary |badge-beta|
+Glossary
 ===============================================================================
 
 .. title-hero::
-    :article: Reference
     :icon: fa-solid fa-spell-check
-    :gradient: linear-gradient(90deg, #fff1df, #fffbf5)
     :summary:
         A quick reference to all the terms, phrases, and links you'll encounter
         on this site, your one-stop guide to navigating with ease.
@@ -27,7 +25,7 @@ Glossary |badge-beta|
     - https://github.com/dhru-repository
 
 -------------------------------------------------------------------------------
-Key Terms and Definitions
+Key Terms and Definitions |badge-beta|
 -------------------------------------------------------------------------------
 
 .. glossary::

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -140,6 +140,11 @@ impactful scientific research.
     :maxdepth: 1
 
     _documentation/getting-started
+
+.. toctree::
+    :hidden:
+    :maxdepth: 2
+
     _documentation/open-science-essentials
 
 .. toctree::

diff --git a/docs/source/school-team.rst b/docs/source/school-team.rst
@@ -1,15 +1,13 @@
 .. Author: Akshay Mestry <xa@mes3.dev>
 .. Created on: Friday, August 30 2024
-.. Last updated on: Saturday, September 01 2024
+.. Last updated on: Friday, September 06 2024
 
 ===============================================================================
-SCHOOL Team |badge-beta|
+SCHOOL Team
 ===============================================================================
 
 .. title-hero::
-    :article: Article
     :icon: fa-solid fa-users
-    :gradient: linear-gradient(135deg, #f5e9fe, #fcf8ff)
     :summary:
         Our Alumni, Open Science, Consultation, and Development Team
         collaborate to democratize access to scientific knowledge, ensuring