From 5260050a84632d69dce8dccb617490037f5cfccf Mon Sep 17 00:00:00 2001 From: Matthias Date: Tue, 22 Sep 2026 10:08:55 +0200 Subject: [PATCH 1/9] Update sidebartoc links and use absolute URL for support Cross-project links move from /docs// to /projects//, the path Read the Docs serves subprojects at. They stay root-relative so they resolve against whichever domain serves the page. That keeps navigation working on both docs.cratedb.com and the readthedocs.io domain, where these links are currently broken. The Support link becomes absolute: it points at the regular site, which will no longer be the origin serving these pages. --- src/crate/theme/rtd/sidebartoc.py | 32 +++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) mode change 100644 => 100755 src/crate/theme/rtd/sidebartoc.py diff --git a/src/crate/theme/rtd/sidebartoc.py b/src/crate/theme/rtd/sidebartoc.py old mode 100644 new mode 100755 index 6c62328b..8ad3dd88 --- a/src/crate/theme/rtd/sidebartoc.py +++ b/src/crate/theme/rtd/sidebartoc.py @@ -129,7 +129,7 @@ def _get_toctree(maxdepth=-1, titles_only=True, collapse=False): parts.append(f'Documentation') parts.append(_get_toctree()) parts.append('') - parts.append('
  • All database drivers
    • ') + parts.append('
  • All database drivers
    • ') return ''.join(parts) # Add Guide's toctree entries (Overview, Getting Started, captions, etc.) @@ -156,38 +156,38 @@ def _get_toctree(maxdepth=-1, titles_only=True, collapse=False): else: # Show Guide's navigation structure when viewing other projects # This must be kept in sync with the Guide's index.md toctree - builder.add_nav_link('Overview', '/docs/guide/') - builder.add_nav_link('Getting Started', '/docs/guide/start/') + builder.add_nav_link('Overview', '/projects/guide/') + builder.add_nav_link('Getting Started', '/projects/guide/start/') # BUILD section parts.append(f'

    {ICON_BUILD}Build

    ') - builder.add_nav_link('Load data into CrateDB', '/docs/guide/ingest/') - builder.add_nav_link('Connect / Drivers', '/docs/guide/connect/') - builder.add_nav_link('Integrations', '/docs/guide/integrate/') - builder.add_nav_link('All Features', '/docs/guide/feature/') + builder.add_nav_link('Load data into CrateDB', '/projects/guide/ingest/') + builder.add_nav_link('Connect / Drivers', '/projects/guide/connect/') + builder.add_nav_link('Integrations', '/projects/guide/integrate/') + builder.add_nav_link('All Features', '/projects/guide/feature/') # OPERATIONS section parts.append(f'

    {ICON_OPERATIONS}Operations

    ') - builder.add_nav_link('Installation', '/docs/guide/install/') - builder.add_nav_link('Administration', '/docs/guide/admin/') - builder.add_nav_link('Performance guides', '/docs/guide/performance/') + builder.add_nav_link('Installation', '/projects/guide/install/') + builder.add_nav_link('Administration', '/projects/guide/admin/') + builder.add_nav_link('Performance guides', '/projects/guide/performance/') # Add Reference section with caption parts.append(f'

    {ICON_REFERENCE}References

    ') - builder.add_project_nav_item('CrateDB Cloud', 'CrateDB Cloud', '/docs/cloud/') - builder.add_project_nav_item('CrateDB: Reference', 'CrateDB', '/docs/crate/reference/') + builder.add_project_nav_item('CrateDB Cloud', 'CrateDB Cloud', '/projects/cloud/') + builder.add_project_nav_item('CrateDB: Reference', 'CrateDB', '/projects/crate-reference/') # Add Tools section with caption parts.append(f'

    {ICON_TOOLS}Tools

    ') - builder.add_project_nav_item('CrateDB: Admin UI', 'Admin UI', '/docs/crate/admin-ui/') - builder.add_project_nav_item('CrateDB: Crash CLI', 'CrateDB CLI', '/docs/crate/crash/') - builder.add_project_nav_item('CrateDB Cloud: Croud CLI', 'Cloud CLI', '/docs/cloud/cli/') + builder.add_project_nav_item('CrateDB: Admin UI', 'Admin UI', '/projects/crate-admin-ui/') + builder.add_project_nav_item('CrateDB: Crash CLI', 'CrateDB CLI', '/projects/crate-crash/') + builder.add_project_nav_item('CrateDB Cloud: Croud CLI', 'Cloud CLI', '/projects/cloud-cli/') parts.append('
  • CrateDB MCP
    • ') parts.append('
  • CrateDB Agent Skills
    • ') parts.append('
  • CrateDB Toolkit
    • ') # Add Support and Community links section after a border - parts.append('
  • Support
    • ') + parts.append('
  • Support
    • ') parts.append('
  • Community
    • ') # Other internal docs projects only included in special builds From c645ad1b34630132af5ffab8984e5c5e00795c8d Mon Sep 17 00:00:00 2001 From: Matthias Date: Tue, 22 Sep 2026 10:10:41 +0200 Subject: [PATCH 2/9] Remove ESI and add absolute URLs to header and footer templates The header pulled the cratedb.com navigation in through Fastly's Edge Side Includes, with a hardcoded copy of the menu as the fallback. Read the Docs serves the pages directly, so there is no ESI processor and both are removed. Only the Login and Get Started buttons remain. The logo and the footer legal links were root-relative and resolved only because the pages were served from cratedb.com. On docs.cratedb.com they would point into the documentation, so they are now absolute. --- src/crate/theme/rtd/crate/page.html | 6 - .../rtd/crate/sections/announcement.html | 3 - .../theme/rtd/crate/sections/footer.html | 8 +- .../rtd/crate/sections/header-content.html | 2 +- .../theme/rtd/crate/sections/header.html | 173 +----------------- .../theme/rtd/crate/static/css/custom.css | 8 - 6 files changed, 15 insertions(+), 185 deletions(-) mode change 100644 => 100755 src/crate/theme/rtd/crate/page.html delete mode 100644 src/crate/theme/rtd/crate/sections/announcement.html mode change 100644 => 100755 src/crate/theme/rtd/crate/sections/footer.html mode change 100644 => 100755 src/crate/theme/rtd/crate/sections/header-content.html mode change 100644 => 100755 src/crate/theme/rtd/crate/sections/header.html mode change 100644 => 100755 src/crate/theme/rtd/crate/static/css/custom.css diff --git a/src/crate/theme/rtd/crate/page.html b/src/crate/theme/rtd/crate/page.html old mode 100644 new mode 100755 index 38cf42b8..f9ffb9cb --- a/src/crate/theme/rtd/crate/page.html +++ b/src/crate/theme/rtd/crate/page.html @@ -11,12 +11,6 @@ {%- endtrans -%} -{% block announcement %} -
    - {% include "sections/announcement.html" %} -
    -{% endblock announcement %} - {% block header %}
    diff --git a/src/crate/theme/rtd/crate/sections/announcement.html b/src/crate/theme/rtd/crate/sections/announcement.html deleted file mode 100644 index 9f50bdbb..00000000 --- a/src/crate/theme/rtd/crate/sections/announcement.html +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/src/crate/theme/rtd/crate/sections/footer.html b/src/crate/theme/rtd/crate/sections/footer.html old mode 100644 new mode 100755 index 2c2b65a8..9481eb62 --- a/src/crate/theme/rtd/crate/sections/footer.html +++ b/src/crate/theme/rtd/crate/sections/footer.html @@ -4,7 +4,7 @@
    - +
    diff --git a/src/crate/theme/rtd/crate/sections/header-content.html b/src/crate/theme/rtd/crate/sections/header-content.html old mode 100644 new mode 100755 index 07dfc269..9b139613 --- a/src/crate/theme/rtd/crate/sections/header-content.html +++ b/src/crate/theme/rtd/crate/sections/header-content.html @@ -1,7 +1,7 @@
    - +
    - +
    diff --git a/src/crate/theme/rtd/crate/static/css/custom.css b/src/crate/theme/rtd/crate/static/css/custom.css old mode 100644 new mode 100755 index f247735c..a52ec3e5 --- a/src/crate/theme/rtd/crate/static/css/custom.css +++ b/src/crate/theme/rtd/crate/static/css/custom.css @@ -835,7 +835,6 @@ footer .footer-list a { } } -/* fallback fix when esi is not loaded */ footer .footer-listitem-new a { padding: 0.5rem 0; display: block; @@ -999,10 +998,6 @@ a.social-links__link:first-child .social-links__icon { width: auto; } -.esi-mobile { - display: none; -} - @media (min-width: 768px) and (max-width: 1139px) { .row-fluid .span2 { width: 14.364640883%; @@ -1019,9 +1014,6 @@ a.social-links__link:first-child .social-links__icon { .footer-widget { display: none; } - .esi-mobile { - display: block; - } } /* bold overrides */ From ead89aea36b2402a89984c69593d6ca4a0678bd3 Mon Sep 17 00:00:00 2001 From: Matthias Date: Tue, 22 Sep 2026 10:13:20 +0200 Subject: [PATCH 3/9] fix `search.html` for sql-99 Search on SQL 99 never worked. The snippet loading the search index sat outside any Jinja block, and a template that extends another discards anything outside a block, so it was silently dropped. The page loaded neither searchtools.js nor a results container, and searchindex.js was built on every run but never read. Now loads Sphinx's search machinery and renders into #search-results. Also drops the dead server-side results markup, which referenced an undefined `item` variable, and stops pulling Algolia's scripts into the one project that does not use them. --- src/crate/theme/rtd/crate/search.html | 54 +++++++++++++-------------- 1 file changed, 26 insertions(+), 28 deletions(-) diff --git a/src/crate/theme/rtd/crate/search.html b/src/crate/theme/rtd/crate/search.html index 8f204f88..bfd5754f 100644 --- a/src/crate/theme/rtd/crate/search.html +++ b/src/crate/theme/rtd/crate/search.html @@ -19,15 +19,23 @@ {{ super() }} +{%- if project == 'SQL 99' %} +{# Sphinx's built-in search. `searchindex.js` calls Search.setIndex() itself, so + it only has to be loaded; `searchtools.js` then renders into #search-results. #} + +{%- else %} +{%- endif %} {%- endblock head_extra -%} -{% if project == 'SQL 99' %} - -{% endif %} +{%- block scripts -%} +{{ super() }} +{%- if project == 'SQL 99' %} + + +{%- endif %} +{%- endblock scripts -%} {% block content %} @@ -47,17 +55,17 @@

    {{ _('Search') }}

    {% if project == 'SQL 99' %} -
    - + + - + {# No #search-progress node on purpose: it is empty except for a brief + "Preparing search..." and would otherwise leave a permanent gap next + to the button. searchtools.js checks for it and skips it if absent. #}
    - {% if search_performed %} -

    {{ _('Search Results') }}

    - {% if not search_results %} -

    {{ _('Your search did not match any results.') }}

    - {% endif %} - {% endif %} - {% if search_results %} -
    -
      - {% for href, caption, context in search_results %} -
    • -
      -

      {{ caption }}

      -
      {{ context|e }}
      -
      -
      • - {% endfor %} -
    -
    - {% endif %} + {# searchtools.js reads ?q= and renders the results in here. #} +
    {% else %} @@ -101,9 +97,11 @@

    {{ caption }}

    {% block footer_content %} {{ super() }} +{%- if project != 'SQL 99' %} +{%- endif %} {% endblock footer_content %} From d6a7d50b22ce10de32be78d943dd0515497a7482 Mon Sep 17 00:00:00 2001 From: Matthias Date: Tue, 22 Sep 2026 10:17:44 +0200 Subject: [PATCH 4/9] remove crate-docs from projects.rst & intersphinx to avoid crashes during migration The entry pointed at crate-docs.readthedocs.io/en/latest/, which stops resolving when that project switches to a single-version URL scheme. Sphinx fetches every inventory at build time and every project builds with warnings as errors, so one dead inventory would fail all of them. Nothing referenced the target, and it is a placeholder project. Both the mapping and the matching :ref: in projects.rst can come back once the root project has real content. --- docs/projects.rst | 1 - src/crate/theme/rtd/conf/__init__.py | 1 - 2 files changed, 2 deletions(-) diff --git a/docs/projects.rst b/docs/projects.rst index d216ef0a..3250823c 100644 --- a/docs/projects.rst +++ b/docs/projects.rst @@ -45,5 +45,4 @@ CrateDB Cloud CrateDB Docs ------------ -- :ref:`crate-docs:index` - :ref:`crate-docs-theme:index` diff --git a/src/crate/theme/rtd/conf/__init__.py b/src/crate/theme/rtd/conf/__init__.py index 2551a00b..a3cf908e 100644 --- a/src/crate/theme/rtd/conf/__init__.py +++ b/src/crate/theme/rtd/conf/__init__.py @@ -125,7 +125,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), } From 3454f850f16aa844cc26e1874197fa85719452a1 Mon Sep 17 00:00:00 2001 From: Matthias Date: Tue, 22 Sep 2026 10:20:41 +0200 Subject: [PATCH 5/9] Update `url_path` and `html_baseurl` of all active projects Point every project at docs.cratedb.com/projects/ 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. They now match the intersphinx_mapping keys. html_baseurl stays fixed rather than derived from the serving domain, so every copy declares the same canonical URL wherever it is served and the documentation is only indexed at docs.cratedb.com. theme.py keeps its own base URL, since the theme's documentation is served from its own Read the Docs domain rather than as a subproject. sql-99 becomes a temporary subproject of crate-docs. crate-docs received its missing config. --- src/crate/theme/rtd/conf/cloud.py | 10 ++--- src/crate/theme/rtd/conf/cloud_cli.py | 10 ++--- src/crate/theme/rtd/conf/crate_admin_ui.py | 10 ++--- .../theme/rtd/conf/crate_clients_tools.py | 10 ++--- src/crate/theme/rtd/conf/crate_crash.py | 10 ++--- src/crate/theme/rtd/conf/crate_docs.py | 37 +++++++++++++++++++ src/crate/theme/rtd/conf/crate_howtos.py | 10 ++--- src/crate/theme/rtd/conf/crate_reference.py | 10 ++--- src/crate/theme/rtd/conf/crate_tutorials.py | 10 ++--- src/crate/theme/rtd/conf/cratedb_guide.py | 10 ++--- src/crate/theme/rtd/conf/dbal.py | 10 ++--- src/crate/theme/rtd/conf/doing_docs.py | 14 ++++--- src/crate/theme/rtd/conf/jdbc.py | 10 ++--- src/crate/theme/rtd/conf/npgsql.py | 12 +++--- src/crate/theme/rtd/conf/pdo.py | 10 ++--- src/crate/theme/rtd/conf/python.py | 10 ++--- src/crate/theme/rtd/conf/sql_99.py | 17 +++++++-- .../theme/rtd/conf/sqlalchemy_cratedb.py | 10 ++--- src/crate/theme/rtd/conf/theme.py | 8 ++-- 19 files changed, 141 insertions(+), 87 deletions(-) mode change 100644 => 100755 src/crate/theme/rtd/conf/cloud.py mode change 100644 => 100755 src/crate/theme/rtd/conf/cloud_cli.py mode change 100644 => 100755 src/crate/theme/rtd/conf/crate_admin_ui.py mode change 100644 => 100755 src/crate/theme/rtd/conf/crate_clients_tools.py mode change 100644 => 100755 src/crate/theme/rtd/conf/crate_crash.py create mode 100755 src/crate/theme/rtd/conf/crate_docs.py mode change 100644 => 100755 src/crate/theme/rtd/conf/crate_howtos.py mode change 100644 => 100755 src/crate/theme/rtd/conf/crate_reference.py mode change 100644 => 100755 src/crate/theme/rtd/conf/crate_tutorials.py mode change 100644 => 100755 src/crate/theme/rtd/conf/cratedb_guide.py mode change 100644 => 100755 src/crate/theme/rtd/conf/dbal.py mode change 100644 => 100755 src/crate/theme/rtd/conf/doing_docs.py mode change 100644 => 100755 src/crate/theme/rtd/conf/jdbc.py mode change 100644 => 100755 src/crate/theme/rtd/conf/npgsql.py mode change 100644 => 100755 src/crate/theme/rtd/conf/pdo.py mode change 100644 => 100755 src/crate/theme/rtd/conf/python.py mode change 100644 => 100755 src/crate/theme/rtd/conf/sql_99.py mode change 100644 => 100755 src/crate/theme/rtd/conf/sqlalchemy_cratedb.py mode change 100644 => 100755 src/crate/theme/rtd/conf/theme.py diff --git a/src/crate/theme/rtd/conf/cloud.py b/src/crate/theme/rtd/conf/cloud.py old mode 100644 new mode 100755 index d3d0950d..718f765d --- a/src/crate/theme/rtd/conf/cloud.py +++ b/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 diff --git a/src/crate/theme/rtd/conf/cloud_cli.py b/src/crate/theme/rtd/conf/cloud_cli.py old mode 100644 new mode 100755 index ada57d97..43cf8479 --- a/src/crate/theme/rtd/conf/cloud_cli.py +++ b/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 diff --git a/src/crate/theme/rtd/conf/crate_admin_ui.py b/src/crate/theme/rtd/conf/crate_admin_ui.py old mode 100644 new mode 100755 index 0747a968..ff29b07d --- a/src/crate/theme/rtd/conf/crate_admin_ui.py +++ b/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 diff --git a/src/crate/theme/rtd/conf/crate_clients_tools.py b/src/crate/theme/rtd/conf/crate_clients_tools.py old mode 100644 new mode 100755 index 6c719154..6cc1a46b --- a/src/crate/theme/rtd/conf/crate_clients_tools.py +++ b/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 diff --git a/src/crate/theme/rtd/conf/crate_crash.py b/src/crate/theme/rtd/conf/crate_crash.py old mode 100644 new mode 100755 index 5394133d..d4c9d62b --- a/src/crate/theme/rtd/conf/crate_crash.py +++ b/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 diff --git a/src/crate/theme/rtd/conf/crate_docs.py b/src/crate/theme/rtd/conf/crate_docs.py new file mode 100755 index 00000000..0e8fc1cd --- /dev/null +++ b/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//`. +url_path = "" +html_baseurl = "https://docs.cratedb.com/" + +# This is a project which is not versioned. +version = "" diff --git a/src/crate/theme/rtd/conf/crate_howtos.py b/src/crate/theme/rtd/conf/crate_howtos.py old mode 100644 new mode 100755 index 99bf17b6..a6285c64 --- a/src/crate/theme/rtd/conf/crate_howtos.py +++ b/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 diff --git a/src/crate/theme/rtd/conf/crate_reference.py b/src/crate/theme/rtd/conf/crate_reference.py old mode 100644 new mode 100755 index 5efa422a..31347a90 --- a/src/crate/theme/rtd/conf/crate_reference.py +++ b/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 diff --git a/src/crate/theme/rtd/conf/crate_tutorials.py b/src/crate/theme/rtd/conf/crate_tutorials.py old mode 100644 new mode 100755 index 7f49c905..b8a5ef4a --- a/src/crate/theme/rtd/conf/crate_tutorials.py +++ b/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 diff --git a/src/crate/theme/rtd/conf/cratedb_guide.py b/src/crate/theme/rtd/conf/cratedb_guide.py old mode 100644 new mode 100755 index a5d5d988..9100795b --- a/src/crate/theme/rtd/conf/cratedb_guide.py +++ b/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 = "" diff --git a/src/crate/theme/rtd/conf/dbal.py b/src/crate/theme/rtd/conf/dbal.py old mode 100644 new mode 100755 index 721bbf22..cf4511b7 --- a/src/crate/theme/rtd/conf/dbal.py +++ b/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 diff --git a/src/crate/theme/rtd/conf/doing_docs.py b/src/crate/theme/rtd/conf/doing_docs.py old mode 100644 new mode 100755 index 53eebdbe..72c551ef --- a/src/crate/theme/rtd/conf/doing_docs.py +++ b/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 diff --git a/src/crate/theme/rtd/conf/jdbc.py b/src/crate/theme/rtd/conf/jdbc.py old mode 100644 new mode 100755 index b13a5ac3..c4a82208 --- a/src/crate/theme/rtd/conf/jdbc.py +++ b/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 diff --git a/src/crate/theme/rtd/conf/npgsql.py b/src/crate/theme/rtd/conf/npgsql.py old mode 100644 new mode 100755 index 37929085..412401e6 --- a/src/crate/theme/rtd/conf/npgsql.py +++ b/src/crate/theme/rtd/conf/npgsql.py @@ -22,11 +22,13 @@ 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 Npgsql" html_title = project -# Vanilla Sphinx/RTD `html_baseurl`. -html_baseurl = "https://cratedb.com/docs/npgsql/" +# ARCHIVED: the crate-npgsql repository is archived and is not part of the +# docs.cratedb.com migration. +url_path = "projects/npgsql" +html_baseurl = "https://docs.cratedb.com/%s/" % url_path diff --git a/src/crate/theme/rtd/conf/pdo.py b/src/crate/theme/rtd/conf/pdo.py old mode 100644 new mode 100755 index e0337c25..96e648eb --- a/src/crate/theme/rtd/conf/pdo.py +++ b/src/crate/theme/rtd/conf/pdo.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 PDO" html_title = project -url_path = "docs/pdo" -html_baseurl = "https://cratedb.com/%s/" % url_path +url_path = "projects/pdo" +html_baseurl = "https://docs.cratedb.com/%s/" % url_path diff --git a/src/crate/theme/rtd/conf/python.py b/src/crate/theme/rtd/conf/python.py old mode 100644 new mode 100755 index 473488ed..22b336d5 --- a/src/crate/theme/rtd/conf/python.py +++ b/src/crate/theme/rtd/conf/python.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 Python" html_title = project -url_path = "docs/python" -html_baseurl = "https://cratedb.com/%s/" % url_path +url_path = "projects/python" +html_baseurl = "https://docs.cratedb.com/%s/" % url_path diff --git a/src/crate/theme/rtd/conf/sql_99.py b/src/crate/theme/rtd/conf/sql_99.py old mode 100644 new mode 100755 index 22d16bc7..7d7115fc --- a/src/crate/theme/rtd/conf/sql_99.py +++ b/src/crate/theme/rtd/conf/sql_99.py @@ -22,13 +22,22 @@ 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"SQL 99" html_title = project -html_baseurl = "https://sql-99.readthedocs.io/" +# TEMPORARY, for the docs.cratedb.com migration PoC. +# +# This project is normally standalone, hosted at https://sql-99.readthedocs.io/, +# and therefore has no `url_path`. For the proof of concept, it is wired up as a +# Read the Docs subproject of `crate-docs`, so it needs one. +# +# Revert both lines back to `html_baseurl = "https://sql-99.readthedocs.io/"` +# once the setup has been proven. +url_path = "projects/sql-99" +html_baseurl = "https://docs.cratedb.com/%s/" % url_path # Disable the GitHub feedback area. html_context_custom.update({ diff --git a/src/crate/theme/rtd/conf/sqlalchemy_cratedb.py b/src/crate/theme/rtd/conf/sqlalchemy_cratedb.py old mode 100644 new mode 100755 index 3e0abfec..47cae19e --- a/src/crate/theme/rtd/conf/sqlalchemy_cratedb.py +++ b/src/crate/theme/rtd/conf/sqlalchemy_cratedb.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"SQLAlchemy Dialect" html_title = project -url_path = "docs/sqlalchemy-cratedb" -html_baseurl = "https://cratedb.com/%s/" % url_path +url_path = "projects/sqlalchemy-cratedb" +html_baseurl = "https://docs.cratedb.com/%s/" % url_path # This is a project which is not versioned. version = "" diff --git a/src/crate/theme/rtd/conf/theme.py b/src/crate/theme/rtd/conf/theme.py old mode 100644 new mode 100755 index 8f604a52..b42f5440 --- a/src/crate/theme/rtd/conf/theme.py +++ b/src/crate/theme/rtd/conf/theme.py @@ -23,10 +23,12 @@ from crate.theme.rtd.conf import * # You can change the `project` value to anything you want because -# `src/crate/theme/rtd/crate/sidebartoc.html` does not have a menu item for +# `src/crate/theme/rtd/sidebartoc.py` does not have a menu item for # this project. project = "CrateDB documentation theme" html_title = project -url_path = "docs/theme" -html_baseurl = "https://cratedb.com/%s/" % url_path +# The theme's own documentation is served from its own Read the Docs +# domain, not as a subproject of `crate-docs`, so it carries no +# `projects/` path and needs its own base URL. +html_baseurl = "https://crate-docs-theme.readthedocs.io/" From 581ae911aa314232e2210e4617a32b927d40bb3f Mon Sep 17 00:00:00 2001 From: Matthias Date: Tue, 22 Sep 2026 10:22:54 +0200 Subject: [PATCH 6/9] Remove obsolete `set_proxied_api_host` and `set_proxied_static_path` Both rewrote Read the Docs' root-relative /_/ paths to sit under the proxied path, so injected assets and API calls resolved through Fastly. They have been dead for a while, RTD replaced it with Addons, injected server-side, which never consults the Sphinx build. Nothing in the theme reads either variable. The migration removes the premise anyway: on docs.cratedb.com, /_/ is Read the Docs' own origin, which would make this redundant. --- src/crate/theme/rtd/conf/__init__.py | 39 ---------------------------- 1 file changed, 39 deletions(-) diff --git a/src/crate/theme/rtd/conf/__init__.py b/src/crate/theme/rtd/conf/__init__.py index a3cf908e..a6a412aa 100644 --- a/src/crate/theme/rtd/conf/__init__.py +++ b/src/crate/theme/rtd/conf/__init__.py @@ -290,43 +290,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: @@ -349,8 +312,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 From 3f7b66590d2ab3c23627bf044fdbab291b6b7b79 Mon Sep 17 00:00:00 2001 From: Matthias Date: Tue, 22 Sep 2026 10:24:28 +0200 Subject: [PATCH 7/9] update opengraph URL ogp_site_url is the fallback for the OpenGraph URL when a page has no canonical of its own, so it follows the documentation to its new host. --- src/crate/theme/rtd/conf/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/crate/theme/rtd/conf/__init__.py b/src/crate/theme/rtd/conf/__init__.py index a6a412aa..93803a2b 100644 --- a/src/crate/theme/rtd/conf/__init__.py +++ b/src/crate/theme/rtd/conf/__init__.py @@ -147,7 +147,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" From 083a56040d0733815a5ad52edccc65008d52b4af Mon Sep 17 00:00:00 2001 From: Matthias Date: Tue, 22 Sep 2026 10:41:41 +0200 Subject: [PATCH 8/9] Update changelog & add migration TODO The TODO records why intersphinx_mapping still points at cratedb.com/docs: Sphinx fetches every inventory at build time and every project builds with warnings as errors, so pointing them at a host that does not resolve yet would fail every build. The new URLs are listed above the mapping, ready to flip once docs.cratedb.com serves content. --- CHANGES.rst | 31 ++++++++++++++++++++++++++++ src/crate/theme/rtd/conf/__init__.py | 17 +++++++++++++++ 2 files changed, 48 insertions(+) mode change 100644 => 100755 CHANGES.rst mode change 100644 => 100755 src/crate/theme/rtd/conf/__init__.py diff --git a/CHANGES.rst b/CHANGES.rst old mode 100644 new mode 100755 index a0e0e5c4..e67b6c1f --- a/CHANGES.rst +++ b/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/`` 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 ----------------- diff --git a/src/crate/theme/rtd/conf/__init__.py b/src/crate/theme/rtd/conf/__init__.py old mode 100644 new mode 100755 index 93803a2b..ee285794 --- a/src/crate/theme/rtd/conf/__init__.py +++ b/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 From 79e45203154aeae568ae12151ec65660231db8db Mon Sep 17 00:00:00 2001 From: Matthias Date: Mon, 28 Sep 2026 11:32:30 +0200 Subject: [PATCH 9/9] increase gap in main nav With the menu gone, Login and Get Started could use a bit more space inbetween. --- src/crate/theme/rtd/crate/static/css/custom.css | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/crate/theme/rtd/crate/static/css/custom.css b/src/crate/theme/rtd/crate/static/css/custom.css index a52ec3e5..ffca278a 100755 --- a/src/crate/theme/rtd/crate/static/css/custom.css +++ b/src/crate/theme/rtd/crate/static/css/custom.css @@ -355,7 +355,7 @@ header .navbar { -webkit-box-align: center; -ms-flex-align: center; align-items: center; - gap: 10px; + gap: 20px; } .main-nav ul.menu > li.menu-item { @@ -1857,4 +1857,3 @@ div.cell_output tbody tr:nth-child(odd):hover, div.cell_output tbody tr:nth-child(even):hover { background: rgba(66, 165, 245, 0.2); } -