diff --git a/CHANGES.rst b/CHANGES.rst old mode 100644 new mode 100755 index a0e0e5c48..e67b6c1f9 --- 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/docs/projects.rst b/docs/projects.rst index d216ef0af..3250823ca 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 old mode 100644 new mode 100755 index 2551a00bc..ee2857942 --- 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 @@ -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 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 d3d0950dd..718f765d2 --- 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 ada57d978..43cf84791 --- 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 0747a9682..ff29b07d2 --- 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 6c7191547..6cc1a46b5 --- 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 5394133dd..d4c9d62bc --- 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 000000000..0e8fc1cda --- /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 99bf17b63..a6285c640 --- 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 5efa422a2..31347a909 --- 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 7f49c905d..b8a5ef4a2 --- 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 a5d5d9882..9100795be --- 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 721bbf22d..cf4511b78 --- 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 53eebdbe5..72c551efe --- 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 b13a5ac37..c4a82208b --- 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 379290857..412401e63 --- 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 e0337c250..96e648eb1 --- 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 473488ed2..22b336d57 --- 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 22d16bc7a..7d7115fc4 --- 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 3e0abfec6..47cae19ed --- 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 8f604a52d..b42f54408 --- 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/" 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 38cf42b87..f9ffb9cb4 --- 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/search.html b/src/crate/theme/rtd/crate/search.html index 8f204f880..bfd5754f0 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 %} 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 9f50bdbb5..000000000 --- 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 2c2b65a83..9481eb629 --- 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 07dfc269e..9b1396133 --- 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 f247735ce..ffca278ac --- 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 { @@ -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 */ @@ -1865,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); } - diff --git a/src/crate/theme/rtd/sidebartoc.py b/src/crate/theme/rtd/sidebartoc.py old mode 100644 new mode 100755 index 6c62328bc..8ad3dd887 --- 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