Merge branch 'main' into tests

Author: flpm

.circleci/config.yml

@@ -2,7 +2,7 @@ version: 2.1
 jobs:
   build-book:
     docker:
-      - image: cimg/python:3.9
+      - image: cimg/python:3.13
     steps:
       - checkout
       - run:

.github/workflows/build-book.yml

@@ -20,7 +20,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.9"
+          python-version: "3.13"
 
       - name: Upgrade pip
         run: |
@@ -68,4 +68,4 @@ jobs:
           directory: "_build/html"
           arguments: |
             --ignore-files "/.+\/_static\/.+/,/genindex.html/"
-            --ignore-status-codes "404, 403, 429, 503"
+            --ignore-status-codes "0, 200, 403, 429, 503"

TRANSLATING.md

@@ -287,7 +287,7 @@ If a language is ready to go live, the maintainers will add the language code to
 
 When the guide is built for release in CI, Sphinx will also generate the translated versions of the guide for the languages in the `RELEASE_LANGUAGES` list.
 
-Translations are released in the same way as the English version of the guide, and the translated versions will be available in folders named after the language code. For example, the Spanish translation will be available in [https://www.pyopensci.org/python-package-guide/es/](https://www.pyopensci.org/python-package-guide/es/).
+Translations are released in the same way as the English version of the guide, and the translated versions will be available in folders named after the language code. For example, the Spanish translation will be available at: `https://www.pyopensci.org/python-package-guide/es/` when it is published online.
 
 ## Frequently Asked Questions (FAQ)
 

_ext/__init__.py

@@ -0,0 +1,101 @@
+"""
+Create an RSS feed of tutorials
+
+Cribbed from: https://github.com/python/peps/blob/main/pep_sphinx_extensions/generate_rss.py
+"""
+
+from dataclasses import dataclass, asdict
+from datetime import datetime, UTC
+from email.utils import format_datetime
+from html import escape
+from pprint import pformat
+from typing import TYPE_CHECKING
+from urllib.parse import urljoin
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+
+def _format_rfc_2822(dt: datetime) -> str:
+    datetime = dt.replace(tzinfo=UTC)
+    return format_datetime(datetime, usegmt=True)
+
+
+@dataclass
+class RSSItem:
+    title: str
+    date: datetime
+    description: str
+    url: str
+    author: str = "pyOpenSci"
+
+    @classmethod
+    def from_meta(cls, page_name: str, meta: dict, app: "Sphinx") -> "RSSItem":
+        """Create from a page's metadata"""
+        url = urljoin(app.config.html_baseurl, app.builder.get_target_uri(page_name))
+        # purposely don't use `get` here because we want to error if these fields are absent
+        return RSSItem(
+            title=meta[":og:title"],
+            description=meta[":og:description"],
+            date=datetime.fromisoformat(meta["date"]),
+            author=meta.get(":og:author", "pyOpenSci"),
+            url=url,
+        )
+
+    def render(self) -> str:
+        return f"""\
+<item>
+  <title>{escape(self.title, quote=False)}</title>
+  <link>{escape(self.url, quote=False)}</link>
+  <description>{escape(self.description, quote=False)}</description>
+  <author>{escape(self.author, quote=False)}</author>
+  <guid isPermaLink="true">{self.url}</guid>
+  <pubDate>{_format_rfc_2822(self.date)}</pubDate>
+</item>"""
+
+
+@dataclass
+class RSSFeed:
+    items: list[RSSItem]
+    last_build_date: datetime = datetime.now()
+    title: str = "pyOpenSci Tutorials"
+    link: str = "https://www.pyopensci.org/python-package-guide/tutorials/intro.html"
+    self_link: str = "https://www.pyopensci.org/python-package-guide/tutorials.rss"
+    description: str = "Tutorials for learning python i guess!!!"
+    language: str = "en"
+
+    def render(self) -> str:
+        items = sorted(self.items, key=lambda i: i.date, reverse=True)
+        items = "\n".join([item.render() for item in items])
+        return f"""\
+<?xml version='1.0' encoding='UTF-8'?>
+<rss xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" version="2.0">
+  <channel>
+    <title>{self.title}</title>
+    <link>{self.link}</link>
+    <atom:link href="{self.self_link}" rel="self"/>
+    <description>{self.description}</description>
+    <language>{self.language}</language>
+    <lastBuildDate>{_format_rfc_2822(self.last_build_date)}</lastBuildDate>
+{items}
+  </channel>
+</rss>
+        """
+
+
+def generate_tutorials_feed(app: "Sphinx"):
+    from sphinx.util import logging
+
+    logger = logging.getLogger("_ext.rss")
+    logger.info("Generating RSS feed for tutorials")
+    metadata = app.builder.env.metadata
+    tutorials = [t for t in metadata if t.startswith("tutorials/")]
+    feed_items = [RSSItem.from_meta(t, metadata[t], app) for t in tutorials]
+    feed = RSSFeed(items=feed_items)
+    with open(app.outdir / "tutorials.rss", "w") as f:
+        f.write(feed.render())
+
+    logger.info(
+        f"Generated RSS feed for tutorials, wrote to {app.outdir / 'tutorials.rss'}"
+    )
+    logger.debug(f"feed items: \n{pformat([asdict(item) for item in feed_items])}")

_ext/rss.py

@@ -38,6 +38,6 @@ @misc{creativecommonsShareAlikeCompatibilityGPLv32015
   year = {2015},
   month = sep,
   journal = {Creative Commons Wiki},
-  url = {https://wiki.creativecommons.org/wiki/ShareAlike\_compatibility:\_GPLv3},
+  url = {https://wiki.creativecommons.org/wiki/ShareAlike_compatibility:_GPLv3},
   urldate = {2024-03-02}
 }

bibliography.bib

@@ -10,12 +10,17 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('.'))
 from datetime import datetime
 import subprocess
 import os
+from typing import TYPE_CHECKING
+from _ext import rss
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
 
 current_year = datetime.now().year
 organization_name = "pyOpenSci"
@@ -96,9 +101,10 @@
 ]
 
 html_baseurl = "https://www.pyopensci.org/python-package-guide/"
+lang_selector_baseurl = "/python-package-guide/"
 if not sphinx_env == "production":
     # for links in language selector when developing locally
-    html_baseurl = "/"
+    lang_selector_baseurl = "/"
 
 html_theme_options = {
     "announcement": "<p><a href='https://www.pyopensci.org/about-peer-review/index.html'>We run peer review of scientific Python software. Learn more.</a></p>",
@@ -148,7 +154,7 @@
     "github_version": "main",
     "language": language,
     "languages": build_languages,
-    "baseurl": html_baseurl,
+    "baseurl": lang_selector_baseurl,
 }
 
 # Add any paths that contain templates here, relative to this directory.
@@ -198,3 +204,14 @@
 bibtex_bibfiles = ["bibliography.bib"]
 # myst complains about bibtex footnotes because of render order
 suppress_warnings = ["myst.footnote"]
+
+
+def _post_build(app: "Sphinx", exception: Exception | None) -> None:
+    rss.generate_tutorials_feed(app)
+
+
+def setup(app: "Sphinx"):
+    app.connect("build-finished", _post_build)
+
+    # Parallel safety: https://www.sphinx-doc.org/en/master/extdev/index.html#extension-metadata
+    return {"parallel_read_safe": True, "parallel_write_safe": True}

conf.py

@@ -16,7 +16,7 @@ name: moving-pandas-github-community
 width: 80%
 alt: Image showing that the MovingPandas GitHub repository community health page with green checks next to each file including a description, README, code of conduct, contributing, license and issue templates. Note that Security policy has a yellow circle next to it as that is missing from the repo.
 ---
-GitHub community health looks for a readme file among other elements when it evaluates the community level health of your repository. This example is from the [MovingPandas GitHub repo](https://github.com/anitagraser/movingpandas/community) *(screen shot taken Nov 23 2022)*
+GitHub community health looks for a readme file among other elements when it evaluates the community level health of your repository. This example is from the [MovingPandas GitHub repo](https://github.com/movingpandas/movingpandas/community) *(screen shot taken Nov 23 2022)*
 ```
 
 [Snyk](https://snyk.io/advisor/python) is another well-known company that

documentation/repository-files/intro.md

@@ -5,7 +5,7 @@ bibliography:
 
 (license-file)=
 
-# License files for scientific Python open source software
+# License files for Python open source software
 
 :::{button-link} <https://www.pyopensci.org/about-peer-review/>
 :color: primary
@@ -69,7 +69,7 @@ in some cases the license that you want is not available through that online
 process.
 
 :::{admonition} License recommendations from the SciPy package
-[The SciPy documentation has an excellent overview of licenses.](https://docs.scipy.org/doc/scipy/dev/core-dev/index.html#licensing). One of the key elements
+[The SciPy documentation has an excellent overview of licenses.](https://docs.scipy.org/doc/scipy/dev/core-dev/index.html#licensing) One of the key elements
 that these docs recommend is ensuring that the license that you select is
 compatible with licenses used in many parts of the scientific Python ecosystem.
 Below is a highlight of this text which outlines license that are compatible

documentation/repository-files/license-files.md

@@ -1,17 +1,19 @@
 # SOME DESCRIPTIVE TITLE.
-# Copyright (C) 2024, pyOpenSci
+# Copyright (C) 2025, pyOpenSci
 # This file is distributed under the same license as the pyOpenSci Python
 # Package Guide package.
-# FIRST AUTHOR <EMAIL@ADDRESS>, 2024.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2025.
 #
+# Translators:
+# Tetsuo Koyama <[email protected]>, 2025
 #, fuzzy
 msgid ""
 msgstr ""
-"Project-Id-Version: pyOpenSci Python Package Guide \n"
+"Project-Id-Version: pyOpenSci Python Package Guide\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2025-02-17 22:50+0000\n"
-"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
-"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"POT-Creation-Date: 2025-04-20 11:32+0900\n"
+"PO-Revision-Date: 2025-04-14 18:12+0000\n"
+"Last-Translator: Tetsuo Koyama <[email protected]>, 2025\n"
 "Language: ja\n"
 "Language-Team: ja <[email protected]>\n"
 "Plural-Forms: nplurals=1; plural=0;\n"
@@ -42,11 +44,11 @@ msgstr "テスト"
 
 #: ../../index.md:325
 msgid "CI/CD"
-msgstr ""
+msgstr "CI/CD"
 
 #: ../../index.md:325
 msgid "Continuous Integration"
-msgstr ""
+msgstr "継続的インテグレーション"
 
 #: ../../index.md:1
 msgid "pyOpenSci Python Package Guide"
@@ -87,7 +89,6 @@ msgid "About this guide"
 msgstr "このガイドについて"
 
 #: ../../index.md:29
-#, fuzzy
 msgid ""
 "Image with the pyOpenSci flower logo in the upper right hand corner. The "
 "image shows the packaging lifecycle. The graphic shows a high level "
@@ -164,15 +165,14 @@ msgid "_new_ Tutorial Series: Create a Python Package"
 msgstr "_new_ チュートリアルシリーズ: Pythonパッケージの作成"
 
 #: ../../index.md:61
-#, fuzzy
 msgid ""
 "The first round of our community-developed, how to create a Python "
 "package tutorial series for scientists is complete! Join our community "
 "review process or watch development of future tutorials in our [GitHub "
 "repo here](https://github.com/pyOpenSci/python-package-guide)."
 msgstr ""
 "コミュニティが開発した、科学者のためのPythonパッケージの作り方チュートリアルシリーズの第一弾が完成しました！ "
-"コミュニティのレビュープロセスに参加したり、 [Github リポジトリはこちら](https://github.com/pyOpenSci"
+"コミュニティのレビュープロセスに参加したり、 [GitHub リポジトリはこちら](https://github.com/pyOpenSci"
 "/python-package-guide) で今後のチュートリアルの開発を見守ったりしてください。"
 
 #: ../../index.md:71
@@ -221,11 +221,11 @@ msgstr "[Hatch入門](/tutorials/get-to-know-hatch)"
 
 #: ../../index.md:102
 msgid "✿ Reference Guides ✿"
-msgstr ""
+msgstr "✿ リファレンスガイド ✿"
 
 #: ../../index.md:106
 msgid "[Command Line Reference Guide](/tutorials/command-line-reference)"
-msgstr ""
+msgstr "[コマンドラインリファレンスガイド](/tutorials/command-line-reference)"
 
 #: ../../index.md:111
 msgid "Python Packaging for Scientists"
@@ -391,12 +391,11 @@ msgstr ""
 "doc-syntax)"
 
 #: ../../index.md:192
-#, fuzzy
 msgid ""
 "[Host your docs on Read The Docs or GitHub Pages](/documentation/hosting-"
 "tools/publish-documentation-online)"
 msgstr ""
-"[Read The Docs または Github Pages でドキュメントをホストする](/documentation/hosting-"
+"[Read The Docs または GitHub Pages でドキュメントをホストする](/documentation/hosting-"
 "tools/publish-documentation-online)"
 
 #: ../../index.md:198
@@ -458,7 +457,6 @@ msgid ""
 msgstr "このガイドへのご貢献をお待ちしております。貢献方法についてはこちらをご覧ください。"
 
 #: ../../index.md:255
-#, fuzzy
 msgid ""
 "xkcd comic showing a stick figure on the ground and one in the air. The "
 "one on the ground is saying. `You're flying! how?`  The person in the air"
@@ -544,11 +542,10 @@ msgstr ""
 "forum](https://pyopensci.discourse.group/) をご利用ください。"
 
 #: ../../index.md:289
-#, fuzzy
 msgid ""
 "This living Python packaging guide is updated as tools and best practices"
 " evolve in the Python packaging ecosystem. We will be adding new content "
 "over the next year."
 msgstr ""
-"これは Python のパッケージングエコシステムにおけるツールやベストプラクティスの進化に合わせて更新される生きたガイドです。 "
-"来年にかけて新しいコンテンツを追加していく予定です。"
+"これは Python のパッケージングエコシステムにおけるツールやベストプラクティスの進化に合わせて更新されるこの生きた Python "
+"パッケージングガイドです。 来年にかけて新しいコンテンツを追加していく予定です。"