Prepare theme for migration to docs.cratedb.com

CHANGES.rst

@@ -5,6 +5,37 @@ CHANGES
 
 Unreleased
 ----------
+- Point ``html_baseurl`` of all projects at ``docs.cratedb.com``, keeping the
+  static form the modules already used. ``theme.py`` keeps its own base URL.
+- Add ``crate.theme.rtd.conf.crate_docs`` configuration for ``crate-docs``,
+  the root project of the documentation site
+- Remove the Edge Side Includes navigation from ``sections/header.html``,
+  together with its inline fallback menu. Only the "Login" and "Get Started"
+  buttons remain
+- Remove ``sections/announcement.html`` and its ``page.html`` block, which
+  contained nothing but an ESI include
+- Remove the orphaned ``.esi-mobile`` rules from ``custom.css``
+- Remove ``set_proxied_api_host()`` and ``set_proxied_static_path()``. Both
+  were dead code and they are unnecessary when Read the Docs serves the 
+  documentation from the web root of its own domain
+- Migrate ``url_path`` of all projects to the ``projects/<slug>`` prefix used
+  for Read the Docs subprojects. Slugs are flat, because a Read the Docs
+  subproject alias is a single path segment: ``crate/reference`` becomes
+  ``crate-reference``, ``cloud/cli`` becomes ``cloud-cli``, and so on. The
+  slugs now match the ``intersphinx_mapping`` keys
+- Make links to ``cratedb.com`` absolute, so they no longer resolve
+  against the documentation domain
+- Update ``ogp_site_url`` and the cross-project links in ``sidebartoc.py``
+- Update the "Get Started" link to ``https://cratedb.com/start-free``
+- Fix: SQL 99 search was non-functional. The snippet loading the search index
+  sat outside any Jinja block in ``search.html``, so it was silently discarded
+  when the template was rendered, and the page pulled in neither
+  ``searchtools.js`` nor a results container. It now loads Sphinx's search
+  machinery and renders into ``#search-results``
+- Remove the ``crate-docs`` entry from ``intersphinx_mapping``, and the
+  matching ``:ref:`` in ``docs/projects.rst``. It pointed at ``/en/latest/``,
+  which breaks when that project switches to a single-version URL scheme
+
 
 2026/03/23 0.50.3
 -----------------

docs/projects.rst

@@ -45,5 +45,4 @@ CrateDB Cloud
 CrateDB Docs
 ------------
 
-- :ref:`crate-docs:index`
 - :ref:`crate-docs-theme:index`

src/crate/theme/rtd/conf/__init__.py

@@ -100,6 +100,23 @@
 ]
 
 # Configure intersphinx mapping
+#
+# TODO: Flip these to https://docs.cratedb.com/projects/... as part of the
+#       migration, but only *after* that domain actually serves content.
+#
+#       New URLs, for reference when the time comes:
+#         guide               -> https://docs.cratedb.com/projects/guide/
+#         crate-reference     -> https://docs.cratedb.com/projects/crate-reference/en/latest/
+#         crate-admin-ui      -> https://docs.cratedb.com/projects/crate-admin-ui/en/latest/
+#         crate-crash         -> https://docs.cratedb.com/projects/crate-crash/en/latest/
+#         crate-dbal          -> https://docs.cratedb.com/projects/dbal/en/latest/
+#         crate-jdbc          -> https://docs.cratedb.com/projects/jdbc/en/latest/
+#         crate-npgsql        -> https://docs.cratedb.com/projects/npgsql/en/latest/
+#         crate-pdo           -> https://docs.cratedb.com/projects/pdo/en/latest/
+#         crate-python        -> https://docs.cratedb.com/projects/python/en/latest/
+#         sqlalchemy-cratedb  -> https://docs.cratedb.com/projects/sqlalchemy-cratedb/
+#         cloud               -> https://docs.cratedb.com/projects/cloud/en/latest/
+#         cloud-cli           -> https://docs.cratedb.com/projects/cloud-cli/en/latest/
 intersphinx_mapping = {
 
     # CrateDB General
@@ -125,7 +142,6 @@
     'sql-99': ('https://sql-99.readthedocs.io/en/latest/', None),
 
     # CrateDB Docs
-    'crate-docs': ('https://crate-docs.readthedocs.io/en/latest/', None),
     'crate-docs-theme': ('https://crate-docs-theme.readthedocs.io/en/latest/', None),
 }
 
@@ -148,7 +164,7 @@
 #   So you can either treat it as 110, or, write your Descriptions to 300 but make sure the first 110
 #   is the critical part and still makes sense when it gets cut off.
 #   -- https://stackoverflow.com/questions/8914476/facebook-open-graph-meta-tags-maximum-content-length
-ogp_site_url = "https://cratedb.com/docs/"
+ogp_site_url = "https://docs.cratedb.com/"
 ogp_description_length = 300
 ogp_site_name = "CrateDB Documentation"
 ogp_image = "https://crate-docs-theme.readthedocs.io/en/latest/_static/images/cratedb-logo-h630.png"
@@ -291,43 +307,6 @@ def configure_self_hosted_on_path(app_inited):
         # render it in `base.html` manually.
         config.html_context["custom_baseurl"] = html_baseurl_real
 
-    # Dynamically set the `proxied_api_host` context variable on a per-project level.
-    def set_proxied_api_host(app_inited):
-        try:
-
-            # Compute appropriate per-project `proxied_api_host`.
-            html_baseurl = app_inited.env.config.html_baseurl.strip("/")
-            proxied_api_host = html_baseurl + "/_"
-
-            # Propagate the `proxied_api_host` to different contexts by trial-and-error.
-            app_inited.env.config.proxied_api_host = proxied_api_host
-            app_inited.builder.config.proxied_api_host = proxied_api_host
-            app_inited.env.config.html_context["proxied_api_host"] = proxied_api_host
-            app_inited.builder.config.html_context["proxied_api_host"] = proxied_api_host
-            print(f"INFO: Adjusted `proxied_api_host` to {proxied_api_host}")
-
-        except Exception as ex:
-            print(f"ERROR: Unable to adjust `proxied_api_host`. Reason: {ex}")
-
-    # Dynamically adjust the `proxied_static_path` context variable on a per-project level.
-    # https://github.com/crate/crate-docs-theme/issues/342
-    def set_proxied_static_path(app_inited):
-        try:
-
-            # The default is `'proxied_static_path': "/_/static/"`.
-            # However, we want it to be, e.g., https://cratedb.com/docs/crate/howtos/_/static/
-            html_baseurl = app_inited.env.config.html_baseurl.strip("/")
-            proxied_static_path = f"{html_baseurl}/_/static/"
-
-            # Propagate the `proxied_api_host` to different contexts by trial-and-error.
-            app_inited.env.config.html_context["proxied_static_path"] = proxied_static_path
-            app_inited.builder.config.html_context["proxied_static_path"] = proxied_static_path
-
-            print(f"INFO: Adjusted `proxied_static_path` to {proxied_static_path}")
-
-        except Exception as ex:
-            print(f"ERROR: Unable to adjust `proxied_static_path`. Reason: {ex}")
-
     # Apply all attributes from `html_context_custom` to `html_context`.
     def apply_html_context_custom(app_inited):
         try:
@@ -350,8 +329,6 @@ def apply_html_context_custom(app_inited):
 
     # Customizations.
     app.connect("builder-inited", configure_self_hosted_on_path)
-    app.connect("builder-inited", set_proxied_api_host)
-    app.connect("builder-inited", set_proxied_static_path)
     app.connect("builder-inited", apply_html_context_custom)
 
     # Register stepper directive

src/crate/theme/rtd/conf/cloud.py

@@ -22,11 +22,11 @@
 
 from crate.theme.rtd.conf import *
 
-# If you update the `project` value here, you must update it in the
-# `src/crate/theme/rtd/crate/sidebartoc.html` file or else Sphinx will not
-# expand the sidebar TOC for this project.
+# If you update the `project` value here, you must update it in
+# `src/crate/theme/rtd/sidebartoc.py` as well, or else the sidebar TOC will
+# not be expanded for this project.
 project = "CrateDB Cloud"
 html_title = project
 
-url_path = "docs/cloud"
-html_baseurl = "https://cratedb.com/%s/" % url_path
+url_path = "projects/cloud"
+html_baseurl = "https://docs.cratedb.com/%s/" % url_path

src/crate/theme/rtd/conf/cloud_cli.py

@@ -22,11 +22,11 @@
 
 from crate.theme.rtd.conf import *
 
-# If you update the `project` value here, you must update it in the
-# `src/crate/theme/rtd/crate/sidebartoc.html` file or else Sphinx will not
-# expand the sidebar TOC for this project.
+# If you update the `project` value here, you must update it in
+# `src/crate/theme/rtd/sidebartoc.py` as well, or else the sidebar TOC will
+# not be expanded for this project.
 project = u"CrateDB Cloud: Croud CLI"
 html_title = project
 
-url_path = "docs/cloud/cli"
-html_baseurl = "https://cratedb.com/%s/" % url_path
+url_path = "projects/cloud-cli"
+html_baseurl = "https://docs.cratedb.com/%s/" % url_path

src/crate/theme/rtd/conf/crate_admin_ui.py

@@ -22,11 +22,11 @@
 
 from crate.theme.rtd.conf import *
 
-# If you update the `project` value here, you must update it in the
-# `src/crate/theme/rtd/crate/sidebartoc.html` file or else Sphinx will not
-# expand the sidebar TOC for this project.
+# If you update the `project` value here, you must update it in
+# `src/crate/theme/rtd/sidebartoc.py` as well, or else the sidebar TOC will
+# not be expanded for this project.
 project = u"CrateDB: Admin UI"
 html_title = project
 
-url_path = "docs/crate/admin-ui"
-html_baseurl = "https://cratedb.com/%s/" % url_path
+url_path = "projects/crate-admin-ui"
+html_baseurl = "https://docs.cratedb.com/%s/" % url_path

src/crate/theme/rtd/conf/crate_clients_tools.py

@@ -22,11 +22,11 @@
 
 from crate.theme.rtd.conf import *
 
-# If you update the `project` value here, you must update it in the
-# `src/crate/theme/rtd/crate/sidebartoc.html` file or else Sphinx will not
-# expand the sidebar TOC for this project.
+# If you update the `project` value here, you must update it in
+# `src/crate/theme/rtd/sidebartoc.py` as well, or else the sidebar TOC will
+# not be expanded for this project.
 project = u"CrateDB: Clients and Tools"
 html_title = project
 
-url_path = "docs/crate/clients-tools"
-html_baseurl = "https://cratedb.com/%s/" % url_path
+url_path = "projects/crate-clients-tools"
+html_baseurl = "https://docs.cratedb.com/%s/" % url_path

src/crate/theme/rtd/conf/crate_crash.py

@@ -22,11 +22,11 @@
 
 from crate.theme.rtd.conf import *
 
-# If you update the `project` value here, you must update it in the
-# `src/crate/theme/rtd/crate/sidebartoc.html` file or else Sphinx will not
-# expand the sidebar TOC for this project.
+# If you update the `project` value here, you must update it in
+# `src/crate/theme/rtd/sidebartoc.py` as well, or else the sidebar TOC will
+# not be expanded for this project.
 project = u"CrateDB: Crash CLI"
 html_title = project
 
-url_path = "docs/crate/crash"
-html_baseurl = "https://cratedb.com/%s/" % url_path
+url_path = "projects/crate-crash"
+html_baseurl = "https://docs.cratedb.com/%s/" % url_path

src/crate/theme/rtd/conf/crate_docs.py

@@ -0,0 +1,37 @@
+# -*- coding: utf-8; -*-
+#
+# Licensed to Crate (https://crate.io) under one or more contributor
+# license agreements.  See the NOTICE file distributed with this work for
+# additional information regarding copyright ownership.  Crate licenses
+# this file to you 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
+#
+#   http://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.
+#
+# However, if you have executed another commercial license agreement
+# with Crate these terms will supersede the license and you may use the
+# software solely pursuant to the terms of the relevant commercial agreement.
+
+from crate.theme.rtd.conf import *
+
+# If you update the `project` value here, you must update it in
+# `src/crate/theme/rtd/sidebartoc.py` as well, or else the sidebar TOC will not
+# be expanded for this project.
+project = "CrateDB Documentation"
+html_title = project
+
+# This is the root project of the documentation site. It is served from the
+# web root of the custom domain, so it does not carry a path prefix, unlike
+# the subprojects below `/projects/<slug>/`.
+url_path = ""
+html_baseurl = "https://docs.cratedb.com/"
+
+# This is a project which is not versioned.
+version = ""

src/crate/theme/rtd/conf/crate_howtos.py

@@ -22,11 +22,11 @@
 
 from crate.theme.rtd.conf import *
 
-# If you update the `project` value here, you must update it in the
-# `src/crate/theme/rtd/crate/sidebartoc.html` file or else Sphinx will not
-# expand the sidebar TOC for this project.
+# If you update the `project` value here, you must update it in
+# `src/crate/theme/rtd/sidebartoc.py` as well, or else the sidebar TOC will
+# not be expanded for this project.
 project = u"CrateDB: How-Tos"
 html_title = project
 
-url_path = "docs/crate/howtos"
-html_baseurl = "https://cratedb.com/%s/" % url_path
+url_path = "projects/crate-howtos"
+html_baseurl = "https://docs.cratedb.com/%s/" % url_path

src/crate/theme/rtd/conf/crate_reference.py

@@ -22,11 +22,11 @@
 
 from crate.theme.rtd.conf import *
 
-# If you update the `project` value here, you must update it in the
-# `src/crate/theme/rtd/crate/sidebartoc.html` file or else Sphinx will not
-# expand the sidebar TOC for this project.
+# If you update the `project` value here, you must update it in
+# `src/crate/theme/rtd/sidebartoc.py` as well, or else the sidebar TOC will
+# not be expanded for this project.
 project = u"CrateDB: Reference"
 html_title = project
 
-url_path = "docs/crate/reference"
-html_baseurl = "https://cratedb.com/%s/" % url_path
+url_path = "projects/crate-reference"
+html_baseurl = "https://docs.cratedb.com/%s/" % url_path

src/crate/theme/rtd/conf/crate_tutorials.py

@@ -22,11 +22,11 @@
 
 from crate.theme.rtd.conf import *
 
-# If you update the `project` value here, you must update it in the
-# `src/crate/theme/rtd/crate/sidebartoc.html` file or else Sphinx will not
-# expand the sidebar TOC for this project.
+# If you update the `project` value here, you must update it in
+# `src/crate/theme/rtd/sidebartoc.py` as well, or else the sidebar TOC will
+# not be expanded for this project.
 project = u"CrateDB: Tutorials"
 html_title = project
 
-url_path = "docs/crate/tutorials"
-html_baseurl = "https://cratedb.com/%s/" % url_path
+url_path = "projects/crate-tutorials"
+html_baseurl = "https://docs.cratedb.com/%s/" % url_path

src/crate/theme/rtd/conf/cratedb_guide.py

@@ -22,14 +22,14 @@
 
 from crate.theme.rtd.conf import *
 
-# If you update the `project` value here, you must update it in the
-# `src/crate/theme/rtd/crate/sidebartoc.html` file or else Sphinx will not
-# expand the sidebar TOC for this project.
+# If you update the `project` value here, you must update it in
+# `src/crate/theme/rtd/sidebartoc.py` as well, or else the sidebar TOC will
+# not be expanded for this project.
 project = u"CrateDB: Guide"
 html_title = project
 
-url_path = "docs/guide"
-html_baseurl = "https://cratedb.com/%s/" % url_path
+url_path = "projects/guide"
+html_baseurl = "https://docs.cratedb.com/%s/" % url_path
 
 # This is a project which is not versioned.
 version = ""

src/crate/theme/rtd/conf/dbal.py

@@ -22,11 +22,11 @@
 
 from crate.theme.rtd.conf import *
 
-# If you update the `project` value here, you must update it in the
-# `src/crate/theme/rtd/crate/sidebartoc.html` file or else Sphinx will not
-# expand the sidebar TOC for this project.
+# If you update the `project` value here, you must update it in
+# `src/crate/theme/rtd/sidebartoc.py` as well, or else the sidebar TOC will
+# not be expanded for this project.
 project = u"CrateDB DBAL"
 html_title = project
 
-url_path = "docs/dbal"
-html_baseurl = "https://cratedb.com/%s/" % url_path
+url_path = "projects/dbal"
+html_baseurl = "https://docs.cratedb.com/%s/" % url_path

src/crate/theme/rtd/conf/doing_docs.py

@@ -22,11 +22,15 @@
 
 from crate.theme.rtd.conf import *
 
-# If you update the `project` value here, you must update it in the
-# `src/crate/theme/rtd/crate/sidebartoc.html` file or else Sphinx will not
-# expand the sidebar TOC for this project.
+# If you update the `project` value here, you must update it in
+# `src/crate/theme/rtd/sidebartoc.py` as well, or else the sidebar TOC will
+# not be expanded for this project.
 project = u"Doing Docs"
 html_title = project
 
-url_path = "docs/meta"
-html_baseurl = "https://cratedb.com/%s/" % url_path
+# NOTE: this project is not published anywhere at the moment -
+# `cratedb.com/docs/meta` returns 404 and there is no Read the Docs
+# project for it. The URL below is provisional, for if it is ever
+# added as a subproject.
+url_path = "projects/meta"
+html_baseurl = "https://docs.cratedb.com/%s/" % url_path

src/crate/theme/rtd/conf/jdbc.py

@@ -22,11 +22,11 @@
 
 from crate.theme.rtd.conf import *
 
-# If you update the `project` value here, you must update it in the
-# `src/crate/theme/rtd/crate/sidebartoc.html` file or else Sphinx will not
-# expand the sidebar TOC for this project.
+# If you update the `project` value here, you must update it in
+# `src/crate/theme/rtd/sidebartoc.py` as well, or else the sidebar TOC will
+# not be expanded for this project.
 project = u"CrateDB JDBC"
 html_title = project
 
-# Vanilla Sphinx/RTD `html_baseurl`.
-html_baseurl = "https://cratedb.com/docs/jdbc/"
+url_path = "projects/jdbc"
+html_baseurl = "https://docs.cratedb.com/%s/" % url_path