Merge branch '6.0' into dev-guide-create-a-backend-add-on

Author: erral

docs/_inc/_add-on-complete-install.md

@@ -0,0 +1,7 @@
+In your web browser, and assuming you are currently logged in as an administrator, visit the URL http://localhost:8080/Plone/prefs_install_products_form.
+
+Then click the {guilabel}`Install` button next to your add-on to complete installation of the add-on.
+
+Some add-ons have configuration options.
+To configure such add-ons, return to the {guilabel}`Site Setup` control panel.
+At the bottom of the page, you should see the heading {guilabel}`Add-on Configuration`, and a control panel to configure the add-on that you just installed.

docs/_inc/_build-and-restart.md

@@ -0,0 +1,35 @@
+If the backend is running, stop it with {kbd}`ctrl-c`.
+
+To actually download and install the package, run the following command.
+
+`````{tab-set}
+````{tab-item} uv
+:sync: uv
+
+```shell
+make backend-build
+```
+````
+
+````{tab-item} pip
+:sync: pip
+
+```shell
+make backend-build
+```
+````
+
+````{tab-item} Buildout
+:sync: buildout
+
+```shell
+bin/buildout -N
+```
+````
+`````
+
+Next, restart the backend.
+
+```{seealso}
+{doc}`run-plone`
+```

docs/_static/documentation.css

@@ -0,0 +1,69 @@
+/*
+  Remove the external link icon from Plone Sphinx Theme for links
+  in submodules that refer to Plone 6 Documentation via Intersphinx.
+  Although these links have `external` in their class, they are
+  actually internal to Plone 6 Documentation.
+*/
+.reference.external::after {
+  all: unset;
+}
+a:not([title="(in Plone Documentation v6)"]).reference.external::after {
+  margin-left: .3em;
+  display: inline-block;
+  content: var(--pst-icon-external-link);
+  white-space: nowrap;
+  font: var(--fa-font-solid);
+  font-size: .75em;
+}
+
+/* Search form styling */
+.bd-search {
+  max-width: 600px;
+}
+
+.bd-search .input-group-text {
+  background-color: var(--pst-color-surface);
+  border-color: var(--pst-color-border);
+  color: var(--pst-color-text-muted);
+}
+
+.bd-search .form-control,
+.bd-search .form-select {
+  border-color: var(--pst-color-border);
+  background-color: var(--pst-color-surface);
+  color: var(--pst-color-text-base);
+}
+
+.bd-search .form-control:focus,
+.bd-search .form-select:focus {
+  border-color: var(--pst-color-primary);
+  box-shadow: 0 0 0 0.2rem rgba(var(--pst-color-primary-rgb), 0.25);
+}
+
+.bd-search .form-label {
+  font-weight: 500;
+  color: var(--pst-color-text-base);
+}
+
+.bd-search .search-button__kbd-shortcut kbd {
+  background-color: var(--pst-color-text-muted);
+  color: var(--pst-color-surface);
+  padding: 0.1rem 0.3rem;
+  border-radius: 3px;
+  font-size: 0.85em;
+}
+
+.bd-search-container ul.search {
+  padding-inline-start: 0;
+}
+
+/* Search results styling */
+#search-results .breadcrumbs {
+  font-size: 0.85em;
+  color: var(--pst-color-text-muted);
+  margin-bottom: 0.25rem;
+}
+
+#search-results .breadcrumbs .pathseparator {
+  padding: 0 0.5em;
+}

docs/_static/search.css

@@ -244,6 +244,7 @@ if (typeof splitQuery === "undefined") {
 const Search = {
   _index: null,
   _queued_query: null,
+  _queued_section: null,
   _pulse_status: -1,
 
   htmlToText: (htmlString, anchor) => {
@@ -252,30 +253,35 @@ const Search = {
       htmlElement.querySelectorAll(removalQuery).forEach((el) => { el.remove() });
     }
     if (anchor) {
-      const anchorContent = htmlElement.querySelector(`[role="main"] ${anchor}`);
+      const anchorContent = htmlElement.querySelector(`.bd-article ${anchor}`);
       if (anchorContent) return anchorContent.textContent;
 
       console.warn(
-        `Anchored content block not found. Sphinx search tries to obtain it via DOM query '[role=main] ${anchor}'. Check your theme or template.`
+        `Anchored content block not found. Sphinx search tries to obtain it via DOM query '.bd-article ${anchor}'. Check your theme or template.`
       );
     }
 
     // if anchor not specified or not found, fall back to main content
-    const docContent = htmlElement.querySelector('[role="main"]');
+    const docContent = htmlElement.querySelector('.bd-article');
     if (docContent) return docContent.textContent;
 
     console.warn(
-      "Content block not found. Sphinx search tries to obtain it via DOM query '[role=main]'. Check your theme or template."
+      "Content block not found. Sphinx search tries to obtain it via DOM query '.bd-article'. Check your theme or template."
     );
     return "";
   },
 
   init: () => {
     const query = new URLSearchParams(window.location.search).get("q");
+    const section = new URLSearchParams(window.location.search).get("section");
+    const select = document
+      .querySelector('select[name="section"]');
     document
       .querySelectorAll('input[name="q"]')
       .forEach((el) => (el.value = query));
-    if (query) Search.performSearch(query);
+    if (section) select.value = section;
+    else select.value = "all";
+    if (query) Search.performSearch(query, section);
   },
 
   loadIndex: (url) =>
@@ -285,14 +291,19 @@ const Search = {
     Search._index = index;
     if (Search._queued_query !== null) {
       const query = Search._queued_query;
+      const section = Search._queued_section;
       Search._queued_query = null;
-      Search.query(query);
+      Search._queued_section = null;
+      Search.query(query, section);
     }
   },
 
   hasIndex: () => Search._index !== null,
 
-  deferQuery: (query) => (Search._queued_query = query),
+  deferQuery: (query, section) => {
+    Search._queued_query = query;
+    Search._queued_section = section;
+  },
 
   stopPulse: () => (Search._pulse_status = -1),
 
@@ -310,7 +321,7 @@ const Search = {
   /**
    * perform a search for something (or wait until index is loaded)
    */
-  performSearch: (query) => {
+  performSearch: (query, section) => {
     // create the required interface elements
     const searchText = document.createElement("h2");
     searchText.textContent = _("Searching");
@@ -335,8 +346,8 @@ const Search = {
     Search.startPulse();
 
     // index already loaded, the browser was quick!
-    if (Search.hasIndex()) Search.query(query);
-    else Search.deferQuery(query);
+    if (Search.hasIndex()) Search.query(query, section);
+    else Search.deferQuery(query, section);
   },
 
   _parseQuery: (query) => {
@@ -475,10 +486,16 @@ const Search = {
     return results.reverse();
   },
 
-  query: (query) => {
+  query: (query, section) => {
     const [searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms] = Search._parseQuery(query);
-    const results = Search._performSearch(searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms);
-    const qresults = results;
+    let results = Search._performSearch(searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms);
+
+    // Filter results by section
+    if (section && section !== 'all') {
+      results = results.filter(result => {
+        return result[0].split('/')[0] === section;
+      });
+    }
 
     // for debugging
     //Search.lastresults = results.slice();  // a copy

docs/_static/searchtools.js

@@ -0,0 +1,48 @@
+{# A bootstrap-styled field that will direct to the `search.html` page when submitted #}
+<form class="bd-search mt-3 mb-5 p-3"
+      action="{{ pathto('search') }}"
+      method="get">
+  <div class="input-group">
+    <input type="search"
+           class="form-control"
+           name="q"
+           id="search-input"
+           placeholder="{{ theme_search_bar_text }}"
+           aria-label="{{ theme_search_bar_text }}"
+           autocomplete="off"
+           autocorrect="off"
+           autocapitalize="off"
+           spellcheck="false"/>
+    <button class="btn btn-primary" type="submit">
+      <i class="fa-solid fa-magnifying-glass"></i>
+    </button>
+    <!-- <span class="input-group-text search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd>K</kbd></span> -->
+  </div>
+  <div class="facet mt-3">
+    <label for="section" class="form-label">Filter by section</label>
+    <select class="form-select" name="section" id="section" onchange="this.form.submit()">
+      <option value="all">All sections</option>
+      {% for id, title in
+        [
+          ['admin-guide', 'Admin Guide'],
+          ['backend', 'Backend'],
+          ['classic-ui', 'Classic UI'],
+          ['conceptual-guides', 'Conceptual Guides'],
+          ['contributing', 'Contributing to Plone'],
+          ['deployment', 'Deployment'],
+          ['developer-guide', 'Developer Guide'],
+          ['glossary', 'Glossary'],
+          ['i18n-l10n', 'Internationalization and Localization'],
+          ['install', 'Install'],
+          ['overview', 'Overview'],
+          ['reference-guide', 'Reference Guide'],
+          ['upgrade', 'Upgrade'],
+          ['plone.restapi', 'Plone REST API'],
+          ['plone.api', 'Plone API'],
+          ['volto', 'Volto UI'],
+        ] %}
+        <option value="{{id}}">{{ title }}</option>
+      {% endfor %}
+    </select>
+  </div>
+</form>