use pydata sphinx theme

AI Prompts:
claude-sonnet-4-6: <ide_opened_file>The user opened the file ./docs/conf.py in the IDE. This may or may not be related to the current task.</ide_opened_file> I would like this in the left side of each page:  - github stars - link to repository - link to pypi  - link to edit the page

Author: niccokunzmann

Makefile

@@ -21,7 +21,7 @@ venv: $(VENV)/bin/activate
 
 # ── docs ───────────────────────────────────────────────────────────────────
 
-.PHONY: html livehtml clean help clean-python clean-all test
+.PHONY: html livehtml clean help clean-python clean-all test init
 
 html: venv
 	$(SPHINXBUILD) -M html $(SOURCEDIR) $(BUILDDIR) $(SPHINXOPTS)
@@ -42,3 +42,5 @@ help: venv
 
 test: venv
 	$(PYTEST)
+
+init: clean-python venv

docs/_static/js/custom-icons.js

@@ -0,0 +1,19 @@
+FontAwesome.library.add(
+  /**
+   * Custom icon definitions
+   *
+   * see https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/header-links.html#svg-image-icons
+   */
+  {
+    prefix: "fa-custom",
+    iconName: "pypi",
+    icon: [
+      17.313,
+      19.807,
+      [],
+      "e001",
+      // https://simpleicons.org/icons/pypi.svg
+      "m10.383 0.2-3.239 1.1769 3.1883 1.1614 3.239-1.1798zm-3.4152 1.2411-3.2362 1.1769 3.1855 1.1614 3.2369-1.1769zm6.7177 0.00281-3.2947 1.2009v3.8254l3.2947-1.1988zm-3.4145 1.2439-3.2926 1.1981v3.8254l0.17548-0.064132 3.1171-1.1347zm-6.6564 0.018325v3.8247l3.244 1.1805v-3.8254zm10.191 0.20931v2.3137l3.1777-1.1558zm3.2947 1.2425-3.2947 1.1988v3.8254l3.2947-1.1988zm-8.7058 0.45739c0.00929-1.931e-4 0.018327-2.977e-4 0.027485 0 0.25633 0.00851 0.4263 0.20713 0.42638 0.49826 1.953e-4 0.38532-0.29327 0.80469-0.65542 0.93662-0.36226 0.13215-0.65608-0.073306-0.65613-0.4588-6.28e-5 -0.38556 0.2938-0.80504 0.65613-0.93662 0.068422-0.024919 0.13655-0.038114 0.20156-0.039466zm5.2913 0.78369-3.2947 1.1988v3.8247l3.2947-1.1981zm-10.132 1.239-3.2362 1.1769 3.1883 1.1614 3.2362-1.1769zm6.7177 0.00213-3.2926 1.2016v3.8247l3.2926-1.2009zm-3.4124 1.2439-3.2947 1.1988v3.8254l3.2947-1.1988zm-6.6585 0.016195v3.8275l3.244 1.1805v-3.8254zm16.9 0.21143-3.2947 1.1988v3.8247l3.2947-1.1981zm-3.4145 1.2411-3.2926 1.2016v3.8247l3.2926-1.2009zm-3.4145 1.2411-3.2926 1.2016v3.8247l3.2926-1.2009zm-3.4124 1.2432-3.2947 1.1988v3.8254l3.2947-1.1988zm-6.6585 0.019027v3.8247l3.244 1.1805v-3.8254zm13.485 1.4497-3.2947 1.1988v3.8247l3.2947-1.1981zm-3.4145 1.2411-3.2926 1.2016v3.8247l3.2926-1.2009zm2.4018 0.38127c0.0093-1.83e-4 0.01833-3.16e-4 0.02749 0 0.25633 0.0085 0.4263 0.20713 0.42638 0.49826 1.97e-4 0.38532-0.29327 0.80469-0.65542 0.93662-0.36188 0.1316-0.65525-0.07375-0.65542-0.4588-1.95e-4 -0.38532 0.29328-0.80469 0.65542-0.93662 0.06842-0.02494 0.13655-0.03819 0.20156-0.03947zm-5.8142 0.86403-3.244 1.1805v1.4201l3.244 1.1805z",
+    ],
+  },
+);

docs/conf.py

@@ -5,7 +5,10 @@
 release = sphinx_icalendar.__version__
 
 extensions = [
+    "sphinx.ext.viewcode",
+    "sphinx_copybutton",
     "sphinx_icalendar",
+    "sphinx_issues",
 ]
 
 html_theme = "alabaster"
@@ -15,3 +18,60 @@
     "github_user": "pycalendar",
     "github_repo": "sphinx-icalendar",
 }
+
+html_context = {
+    #     "github_url": "https://github.com", # or your GitHub Enterprise site
+    "github_user": html_theme_options["github_user"],
+    "github_repo": html_theme_options["github_repo"],
+    "github_version": "main",
+    "doc_path": "docs",
+}
+
+
+source_suffix = {".rst": "restructuredtext"}
+
+# -- sphinx_copybutton configuration ----------------------------------
+# https://sphinx-copybutton.readthedocs.io/en/latest/use.html
+# Exclude line numbers, prompts, and console output when copying code blocks.
+copybutton_exclude = ".linenos, .gp, .go"
+
+
+# -- sphinx_issues configuration ----------------------------------
+issues_github_path = "pycalendar/sphinx-icalendar"
+
+html_theme_options = {
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/pycalendar/sphinx-icalendar",
+            "icon": "fa-brands fa-square-github",
+            "type": "fontawesome",
+            "attributes": {
+                "target": "_blank",
+                "rel": "noopener me",
+                "class": "nav-link custom-fancy-css",
+            },
+        },
+        {
+            "name": "PyPI",
+            "url": "https://pypi.org/project/sphinx-icalendar",
+            "icon": "fa-custom fa-pypi",
+            "type": "fontawesome",
+            "attributes": {
+                "target": "_blank",
+                "rel": "noopener me",
+                "class": "nav-link custom-fancy-css",
+            },
+        },
+    ],
+    "use_edit_page_button": True,
+}
+
+html_theme = "pydata_sphinx_theme"
+html_static_path = [
+    "_static",
+]
+html_js_files = [
+    ("js/custom-icons.js", {"defer": "defer"}),
+]
+pygments_style = "sphinx"

docs/contributing.rst

@@ -81,10 +81,23 @@ Remove the virtual environment as well:
 New release
 -----------
 
+Before the release, check the documentation and that it renders properly.
+
 To create a new release, run:
 
 .. code-block:: bash
 
     git checkout main
     git tag v0.1.1
     git push origin v0.1.1
+
+Notes on documentation
+----------------------
+
+- Use "iCalendar" when describing a file format that follows that standard.
+- Use "jCal" when describing a file format that follows that standard.
+- Use ".ics" or ".ifb" when describing a file's extension. See :rfc:`5545#section-8.1`.
+- Don't use "ICS" anywhere, including the tabbed interface. It's not used as an acronym in RFC 5545. Use "iCalendar" instead.
+
+.. seealso::
+    :issue:`3`

docs/usage/calendar.rst

@@ -22,8 +22,8 @@ The extension detects the format automatically.
         END:VEVENT
         END:VCALENDAR
 
-Below, we use a different ICS source to show a calendar with a name and description.
-The original ICS formatting is preserved.
+Below, we use a different iCalendar source to show a calendar with a name and description.
+The original iCalendar formatting is preserved.
 
 
 .. code-block:: calendar
@@ -111,11 +111,11 @@ Options
 A ``calendar`` directive support the following options:
 
 - ``:emphasize-lines:`` - A comma-separated list of line numbers to emphasize.
-    This only applies to the source code blocks with ``jcal`` or ``ics`` content.
-- ``:linenos:`` - If set, adds line numbers.
+  This only applies to the source code blocks, not the converted ones.
+- ``:linenos:`` - If set, adds line numbers to all code blocks.
 
 
-Below, you can find an ``ics`` calendar that highlights a single event.
+Below, you can find an iCalendar that highlights a single event.
 
 .. code-block:: rst
 

docs/usage/ics.rst

@@ -1,7 +1,7 @@
-ICS syntax highlighting
-=======================
+iCalendar syntax highlighting
+=============================
 
-The extension also registers an ``ics`` (and ``icalendar``) language alias for Pygments so you can highlight raw ICS snippets in ordinary code blocks without triggering the calendar rendering:
+The extension also registers an ``ics`` (and ``icalendar``) language alias for Pygments so you can highlight raw iCalendar snippets in ordinary code blocks without triggering the calendar rendering:
 
 .. code-block:: rst
 
@@ -30,7 +30,7 @@ The result is a static, highlighted code block:
 Options
 -------
 
-``ics`` supports the ``linenos`` and ``emphasize-lines`` options, just like any
+iCalendar supports the ``linenos`` and ``emphasize-lines`` options, just like any
 other ``.. code-block::`` language:
 
 .. code-block:: rst

docs/usage/jcal.rst

@@ -1,5 +1,5 @@
-jCal syntax highlighting
-========================
+jCalendar syntax highlighting
+=============================
 
 The extension also registers ``jcal`` (and ``jcalendar``) as language aliases that apply JSON highlighting to raw jCal snippets without triggering the calendar rendering:
 
@@ -47,17 +47,6 @@ other ``.. code-block::`` language:
        :linenos:
        :emphasize-lines: 5, 6
 
-        ["vcalendar",
-          [["version", {}, "text", "2.0"]],
-          [["vevent",
-            [
-              ["summary",  {}, "text",      "Quarterly review"],
-              ["dtstart",  {}, "date-time", "2026-04-01T09:00:00Z"],
-              ["dtend",    {}, "date-time", "2026-04-01T10:00:00Z"]
-            ], []
-          ]]
-        ]
-
 .. code-block:: jcal
    :linenos:
    :emphasize-lines: 5, 6

pyproject.toml

@@ -41,12 +41,25 @@ Changelog = "https://sphinx-icalendar.readthedocs.io/en/latest/changelog.html"
 Funding = "https://github.com/sponsors/niccokunzmann"
 
 [project.optional-dependencies]
-dev = ["pytest", "sphinx", "sphinx-autobuild"]
+dev = [
+    "pytest",
+    "pydata-sphinx-theme>=0.14.4",
+    "sphinx>=7",
+    "sphinx-copybutton>=0.5.2",
+    "sphinx-design>=0.5.0",
+    "sphinx-autobuild>=2021.3.14",
+    "sphinx-issues>=5.0.1",
+    "sphinx-llms-txt>=0.7.1",
+]
 
 [project.entry-points."pygments.lexers"]
 ics = "sphinx_icalendar._lexer:ICalendarLexer"
 jcal = "sphinx_icalendar._lexer:JCalLexer"
 
+[tool.hatch.version.raw-options]
+# see https://github.com/ofek/hatch-vcs/issues/43#issuecomment-1553065222
+local_scheme = "no-local-version"
+
 [tool.hatch.version]
 source = "vcs"
 

sphinx_icalendar/_visitors.py

@@ -112,7 +112,7 @@ def visit_calendar_html(self: HTML5Translator, node: calendar_block) -> None:
         f'<div class="sd-tab-content docutils">{table_html}</div>'
         # rendered ics
         f'<input id="cal-{tid}-input--2" name="cal-{tid}" type="radio">'
-        f'<label for="cal-{tid}-input--2">ICS</label>'
+        f'<label for="cal-{tid}-input--2">iCalendar</label>'
         f'<div class="sd-tab-content docutils">{ics_highlighted}</div>'
         # rendered jcal
         f'<input id="cal-{tid}-input--3" name="cal-{tid}" type="radio">'