docs: Add Pigweed Live directive

Docs can use this directive to raise awareness about when the next
Pigweed Live meeting is. The directive ensures that the meeting
date is always in the future.

Change-Id: I313c11b57c5956bcbd69b94f63f73aab506dc8d1
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/174892
Reviewed-by: Rob Mohr <mohrr@google.com>
Reviewed-by: Kayce Basques <kayce@google.com>
Commit-Queue: Kayce Basques <kayce@google.com>

5 files changed, 138 insertions, 0 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 839ca6711..62ba2692a 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -43,6 +43,7 @@ extensions = [
     'pw_docgen.sphinx.google_analytics',  # Enables optional Google Analytics
     'pw_docgen.sphinx.kconfig',
     'pw_docgen.sphinx.module_metadata',
+    'pw_docgen.sphinx.pigweed_live',
     'pw_docgen.sphinx.seed_metadata',
     'sphinx.ext.autodoc',  # Automatic documentation for Python code
     'sphinx.ext.napoleon',  # Parses Google-style docstrings
diff --git a/docs/index.rst b/docs/index.rst
index 93862a5a0..3c129921b 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -48,6 +48,11 @@ STMicroelectronics STM32L452 or the Nordic nRF52832.
    in our `chat room <https://discord.gg/M9NSeTA>`_ or on the `mailing list
    <https://groups.google.com/forum/#!forum/pigweed>`_.
 
+--------------------------
+Talk to us at Pigweed Live
+--------------------------
+.. pigweed-live::
+
 ---------------------
 What's New In Pigweed
 ---------------------
diff --git a/pw_docgen/py/BUILD.gn b/pw_docgen/py/BUILD.gn
index 0f4b511b9..a52f3ab31 100644
--- a/pw_docgen/py/BUILD.gn
+++ b/pw_docgen/py/BUILD.gn
@@ -28,6 +28,7 @@ pw_python_package("py") {
     "pw_docgen/sphinx/google_analytics.py",
     "pw_docgen/sphinx/kconfig.py",
     "pw_docgen/sphinx/module_metadata.py",
+    "pw_docgen/sphinx/pigweed_live.py",
     "pw_docgen/sphinx/seed_metadata.py",
   ]
   pylintrc = "$dir_pigweed/.pylintrc"
diff --git a/pw_docgen/py/pw_docgen/sphinx/pigweed_live.py b/pw_docgen/py/pw_docgen/sphinx/pigweed_live.py
new file mode 100644
index 000000000..f385834b9
--- /dev/null
+++ b/pw_docgen/py/pw_docgen/sphinx/pigweed_live.py
@@ -0,0 +1,130 @@
+# Copyright 2023 The Pigweed Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+"""Docs widget that provides up-to-date info about the next Pigweed Live."""
+
+
+import datetime
+import sys
+from typing import Dict, List
+
+from docutils import nodes
+from docutils.parsers.rst import Directive
+from sphinx.application import Sphinx
+
+try:
+    import pytz  # type: ignore
+
+    PYTZ_AVAILABLE = True
+except ImportError:
+    PYTZ_AVAILABLE = False
+
+
+class PigweedLiveDirective(Directive):
+    """Generates the up-to-date Pigweed Live info."""
+
+    datetime_format = '%Y-%m-%d %H:%M:%S'
+    # TODO: b/303859828 - Update this data sometime between 2024-09-23
+    # and 2024-10-07.
+    meetings = [
+        '2023-10-09 13:00:00',
+        '2023-10-23 13:00:00',
+        '2023-11-06 13:00:00',
+        '2023-11-20 13:00:00',
+        '2023-12-04 13:00:00',
+        '2023-12-18 13:00:00',
+        # 2024-01-01 and 2024-01-15 are skipped because they're holidays.
+        '2024-01-29 13:00:00',
+        '2024-02-12 13:00:00',
+        '2024-02-26 13:00:00',
+        '2024-03-11 13:00:00',
+        '2024-03-25 13:00:00',
+        '2024-04-08 13:00:00',
+        '2024-04-22 13:00:00',
+        '2024-05-06 13:00:00',
+        '2024-05-20 13:00:00',
+        '2024-06-03 13:00:00',
+        '2024-06-17 13:00:00',
+        '2024-07-01 13:00:00',
+        '2024-07-15 13:00:00',
+        '2024-07-29 13:00:00',
+        '2024-08-12 13:00:00',
+        '2024-08-26 13:00:00',
+        '2024-09-09 13:00:00',
+        '2024-09-23 13:00:00',
+        '2024-10-07 13:00:00',
+    ]
+    timezone = pytz.timezone('US/Pacific')
+
+    def run(self) -> List[nodes.Node]:
+        return [self._make_paragraph()]
+
+    def _make_paragraph(self) -> nodes.Node:
+        next_meeting = self._find_next_meeting()
+        paragraph = nodes.paragraph()
+        paragraph += nodes.Text('Our next Pigweed Live is ')
+        meeting_text = nodes.strong()
+        meeting_text += nodes.Text(next_meeting)
+        paragraph += meeting_text
+        paragraph += nodes.Text(
+            (
+                ". Please join us to discuss what's new in Pigweed and "
+                "anything else Pigweed-related. Or stop in just to say hi and "
+                "meet the team! You'll find a link for the meeting in the "
+                "#pigweed-live channel of our "
+            )
+        )
+        link = nodes.reference(refuri='https://discord.gg/M9NSeTA')
+        link += nodes.Text('Discord')
+        paragraph += link
+        paragraph += nodes.Text(
+            (
+                '. We meet bi-weekly. The meeting is public. Everyone is '
+                'welcome to join.'
+            )
+        )
+        return paragraph
+
+    def _find_next_meeting(self) -> str:
+        current_datetime = self.timezone.localize(datetime.datetime.now())
+        next_meeting = None
+        for meeting in self.meetings:
+            unlocalized_datetime = datetime.datetime.strptime(
+                meeting, self.datetime_format
+            )
+            meeting_datetime = self.timezone.localize(unlocalized_datetime)
+            if current_datetime > meeting_datetime:
+                continue
+            next_meeting = meeting_datetime
+            break
+        if next_meeting is None:
+            sys.exit(
+                'ERROR: Pigweed Live meeting data needs to be updated. '
+                'Update the `meetings` list in `PigweedLiveDirective`. '
+                'See b/303859828.'
+            )
+        else:
+            date = next_meeting.strftime('%a %b %d, %Y')
+            hour = next_meeting.strftime('%I%p').lstrip('0')
+            timezone = 'PDT' if next_meeting.dst() else 'PST'
+            return f'{date} {hour} ({timezone})'
+
+
+def setup(app: Sphinx) -> Dict[str, bool]:
+    """Initialize the directive."""
+    if PYTZ_AVAILABLE:
+        app.add_directive('pigweed-live', PigweedLiveDirective)
+    return {
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
diff --git a/pw_env_setup/py/pw_env_setup/virtualenv_setup/pigweed_upstream_requirements.txt b/pw_env_setup/py/pw_env_setup/virtualenv_setup/pigweed_upstream_requirements.txt
index 16834a0bc..54a231aea 100644
--- a/pw_env_setup/py/pw_env_setup/virtualenv_setup/pigweed_upstream_requirements.txt
+++ b/pw_env_setup/py/pw_env_setup/virtualenv_setup/pigweed_upstream_requirements.txt
@@ -19,6 +19,7 @@ furo==2023.8.19
 sphinx-copybutton==0.5.1
 breathe==4.35.0
 kconfiglib==14.1.0
+pytz==2023.3
 # Renode requirements
 psutil==5.9.4
 robotframework==6.0.2