Add RTD stats collection

.github/workflows/rtd_analytics.yml

@@ -0,0 +1,45 @@
+# holder action for if/when RTD Analytics has an API endpoint (not implemented as of June 2026)
+name: Get Read the Docs (RTD) analytics
+on:
+  # schedule:
+  #   # runs once a month on the first
+  #   - cron: "55 20 1 * *"
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  # This workflow contains a single job called "rtd_stats"
+  rtd_stats:
+    # The type of runner that the job will run on
+    runs-on: ubuntu-latest
+    environment:
+      name: read-the-docs
+    permissions:
+      contents: write # for Git to git push
+    if: github.repository_owner == 'icesat2py'
+
+    # Steps represent a sequence of tasks that will be executed as part of the job
+    steps:
+    # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      with:
+        ref: "traffic"
+        persist-credentials: true
+
+    # Pulls RTD stats, adds them to existing CSV file
+    - name: Update rtd stats files
+      env:
+        RTD_API_TOKEN: ${{ secrets.RTD_API_TOKEN }}
+      run: |
+        pip install -U pip
+        pip install -r requirements.txt
+        python ./doc/source/tracking/rtdstats/get_rtd_stats.py
+
+    # Commits files to repository
+    - name: Commit changes
+      uses: EndBug/add-and-commit@290ea2c423ad77ca9c62ae0f5b224379612c0321 # v10.0.0
+      with:
+        author_name: Jessica Scheick
+        message: "RTD analytics auto-update"
+        add: "./doc/source/tracking/rtdstats/*"

.gitignore

@@ -99,6 +99,9 @@ venv.bak/
 # Rope project settings
 .ropeproject
 
+# VSCode project settings
+.vscode
+
 # mkdocs documentation
 /site
 
@@ -128,3 +131,5 @@ venv.bak/
 !views.csv
 !downloads_data.csv
 !sys_downloads_data.csv
+!pageview_data.csv
+!searches_data.csv

.pre-commit-config.yaml

@@ -22,6 +22,7 @@ repos:
     rev: v2.4.2
     hooks:
       - id: codespell
+        exclude: "doc/source/tracking/rtdstats/searches_data.csv"
         additional_dependencies:
           - tomli
 

doc/source/tracking/rtdstats/get_rtd_stats.py

@@ -0,0 +1,86 @@
+import os
+
+import pandas as pd
+
+cwd = os.getcwd()
+
+trackpath = f"{cwd}/doc/source/tracking/rtdstats/"
+pageviewfn = "pageview_data.csv"
+searchfn = "searches_data.csv"
+
+# rtd_token = os.environ["RTD_API_TOKEN"]
+# headers = {"Authorization": f"Token {rtd_token}"}
+# base = "https://app.readthedocs.org"
+
+
+# Turns out you cannot yet get the analytics data from the API, only the UI
+# This function has the scaffolding to get the data if it's ever implemented
+# def fetch_rtd_analytics(url, headers, output_path=None):
+#     """Fetch analytics from a Read the Docs URL and return a DataFrame."""
+#     try:
+#         resp = requests.get(url, headers=headers, timeout=30)
+#         data = resp.json()
+#     except Exception:
+#         return None
+
+#     if not resp.ok:
+#         return None
+
+#     if isinstance(data, dict) and "results" in data:
+#         results = data.get("results", [])
+#         if results:
+#             df = pd.json_normalize(results)
+#             if output_path:
+#                 df.to_csv(output_path, index=False)
+#             return df
+#         return None
+
+#     if isinstance(data, list):
+#         df = pd.json_normalize(data)
+#         if output_path:
+#             df.to_csv(output_path, index=False)
+#         return df
+
+#     return None
+
+
+### Collect the analytics data and combine it with whatever already exists
+### must manually download the csv and rename it to `pageview.csv`
+# pageviews = fetch_rtd_analytics(
+#     f"{base}/api/v3/projects/icepyx/", headers
+# )
+pageviews = pd.read_csv(trackpath + "pageview.csv")
+exist_pageviews = pd.read_csv(trackpath + pageviewfn)
+
+pageviews = pageviews.merge(
+    exist_pageviews, how="outer", on=["Path", "Date", "Version", "Views"]
+)
+
+# remove duplicate entries; sort default is ascending
+pageviews = pageviews.sort_values(["Date"], ignore_index=True).drop_duplicates(
+    subset=["Date", "Version", "Path"], keep="last"
+)
+
+pageviews.sort_values(["Date"], ignore_index=True).to_csv(
+    trackpath + pageviewfn, index=False
+)
+
+# see which pages have most views
+print(pageviews.groupby("Path").sum().sort_values(["Views"], ascending=False))
+
+
+# searches = fetch_rtd_analytics(f"{base}/api/v3/projects/icepyx/search-terms/", headers)
+
+searches = pd.read_csv(trackpath + "searches.csv")
+exist_searches = pd.read_csv(trackpath + searchfn)
+
+searches = searches.merge(
+    exist_searches, how="outer", on=["Created Date", "Query", "Total Results"]
+)
+
+searches.sort_values(["Query"], ignore_index=True).to_csv(
+    trackpath + searchfn, index=False
+)
+
+# print out what most common query words are
+print(searches.groupby("Query").count())