Merge branch '6-dev' into writing-docs-tips

Author: stevepiercy

docs/_static/custom.css

@@ -58,6 +58,11 @@ img.figure,
   margin-bottom: 1rem;
 }
 
+img.inline {
+  margin: 0;
+  height: 1em;
+}
+
 span.linenos {
   padding-right: 1em;
 }
@@ -184,6 +189,25 @@ div.admonition.admonition-todo>.admonition-title::before {
   display: block;
 }
 
+#search-form:focus-within #shortcut-page,
+.bd-search:focus-within #shortcut {
+  display: none;
+}
+
+#shortcut-page.input-group-text {
+  padding-top: 0;
+  padding-bottom: 0;
+}
+
+input#q {
+  border-radius: .25rem 0 0 .25rem;
+}
+
+.form-control:focus {
+  box-shadow: none;
+  border-width: 2px;
+}
+
 ul.search {
   margin-left: 0;
 }
@@ -234,6 +258,45 @@ ul.search li p.context {
   margin-left: 0;
 }
 
+/* Search form sidebar */
+
+.bd-search {
+  font-size: .8rem;
+}
+
+.bd-search:focus-within #search-input {
+  border-radius: .25rem;
+}
+
+#shortcut.input-group-text {
+  padding-top: 0;
+  padding-bottom: 0;
+}
+
+.bd-search input,
+.bd-search .input-group-text {
+  font-size: .8rem;
+  padding-left: .5em;
+}
+
+input#search-input {
+  padding-left: 2.1875rem;
+  border-radius: .25rem 0 0 .25rem;
+}
+
+.search-icon {
+  position: absolute;
+  color: #a4a6a7;
+  left: .625rem;
+  z-index: 100;
+  align-self: center;
+}
+
+.input-group-text kbd {
+  padding: 0rem 0.4rem;
+  font-size: 135%;
+}
+
 .pathseparator {
   padding: 0 0.7rem;
 }

docs/_static/search_shortcut.js

@@ -0,0 +1,35 @@
+/**
+ * Add shortcut `ctrl+k` to focus on search field
+ */
+
+ $(document).ready(() => {
+    if (window.location.pathname === '/search.html') {
+        $('form.bd-search .input-group').hide(); // Hide Sidebar Search field
+
+        $(document).keydown(function(event) {
+            if ((event.ctrlKey || event.metaKey) && event.key == "k") {
+                event.preventDefault();
+                $('#q').focus();
+            }
+        });
+    } else {
+        $(document).keydown(function(event) {
+            if ((event.ctrlKey || event.metaKey) && event.key == "k") {
+                event.preventDefault();
+                $('#search-input').focus();
+            }
+        });
+    }
+    
+    // if OS isn't Mac change visual indication of search field
+    if (navigator.platform.indexOf('Mac') === -1) {
+        $('#search-shortcut').html("^");
+        $('#search-page-shortcut').html("^");
+    }
+    
+});
+
+function onReset() {
+    $('#search-form').trigger('reset');
+    $('#search-form').trigger('submit');
+}

docs/_static/searchtools.js

@@ -342,7 +342,10 @@ var Search = {
       else {
         Search.stopPulse();
         Search.title.text(_('Search Results'));
-        if (!resultCount)
+        if (query === '') {
+          Search.status.text(_('No query, no results.'));
+        }
+        else if (!resultCount)
           Search.status.text(_('Your search did not match any documents. Please make sure that all words are spelled correctly. Searching for multiple words only shows matches that contain all words.'));
         else
             Search.status.text(_('Found %s page(s) matching the search query.').replace('%s', resultCount));

docs/_templates/search-field.html

@@ -0,0 +1,19 @@
+<form class="bd-search d-flex align-items-center" action="{{ pathto('search') }}" method="get">
+  <div class="input-group">
+    <label for="q" class="sr-only">Search string
+    </label>
+    <i class="fa fa-search fa-lg search-icon" aria-hidden="true"></i>
+    <input
+    type="search" name="q" id="search-input"
+    class="form-control"
+    placeholder="{{ _(theme_search_bar_text) }}"
+    aria-labelledby="{{ _(theme_search_bar_text) }}"
+    value="" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"
+    />
+    <div class="input-group-append">
+      <span class="input-group-text" id="shortcut">
+        <kbd id="search-shortcut">⌘</kbd>&nbsp;<kbd>K</kbd>
+      </span>
+    </div>
+  </div>
+</form>

docs/_templates/search.html

@@ -48,20 +48,29 @@ <h1 id="search-documentation">{{ _('Search') }}</h1>
       >
       <div class="row">
         <div class="input-group col-xl-8 mb-2">
+          <label for="q" class="sr-only">Search string
+          </label>
           <input
-            type="text" name="q" id="q"
-            class="form-control"
-            placeholder="Search the docs…"
-            aria-labelledby="search-documentation" value="" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
-          <label for="q" class="sr-only">Search string</label>
+          type="search" name="q" id="q"
+          class="form-control"
+          placeholder="{{ _(theme_search_bar_text) }}"
+          aria-labelledby="{{ _(theme_search_bar_text) }}"
+          value="" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"
+          />
           <div class="input-group-append">
-            <button type="submit" class="btn btn-primary">{{ _('search') }}</button>
+            <span class="input-group-text" id="shortcut-page">
+              <kbd id="search-page-shortcut">⌘</kbd>&nbsp;<kbd>K</kbd>
+            </span>
           </div>
           <div class="input-group-append">
             <button
-              type="button"
-              class="clear_search btn btn-secondary"
-            >{{ _('reset') }}</button>
+            type="button"
+            onclick="onReset()"
+            class="btn btn-danger"
+            ><i class="fas fa-times"></i></button>
+          </div>
+          <div class="input-group-append">
+            <button type="submit" class="btn btn-primary"><i class="fas fa-search fa-lg" aria-hidden="true"></i></button>
           </div>
         </div>
       </div>
@@ -70,7 +79,7 @@ <h1 id="search-documentation">{{ _('Search') }}</h1>
         <label for="doc_section" class="col sr-only">Filter by section</label>
         <div class="col">
           <div class="form-check">
-            <input class="form-check-input" type="radio" name="doc_section" id="doc_section_all" value="all">
+            <input class="form-check-input" type="radio" name="doc_section" id="doc_section_all" value="all" checked>
             <label class="form-check-label" for="doc_section_all">
               All Documentation
             </label>

docs/classic-ui/static-resources.md

@@ -15,12 +15,80 @@ We often want to ship a website with a static resource, such as an image, icon,
 For this, we need to register static resources.
 
 
+(classic-ui-static-resources-registering-label)=
+## Registering javascript and css
+
+To register a static resource in Plone 6, we need to use the `plone.base.interfaces.resources.IBundleRegistry` interface.
+
+The following example registers a Javascript resource in `browser/profiles/default/registry` of your Plone 6 project.
+The js files have to be in the `browser/static` folder of your Plone 6 project.
+
+```xml
+<registry>
+  <records interface="plone.base.interfaces.resources.IBundleRegistry" prefix="plone.bundles/jscript">
+    <value key="enabled">True</value>
+    <value key="jscompilation">++plone++myproject.site/javascript.min.js</value>
+    <value key="load_async">False</value> 
+    <value key="load_defer">False</value>
+    <value key="depends">plone</value>
+  </records>
+</registry>
+```
+
+You can register a CSS resource in the same way.
+  
+```xml
+    <registry>
+    <records interface="plone.base.interfaces.resources.IBundleRegistry" prefix="plone.bundles/css">
+      <value key="enabled">True</value>
+      <value key="csscompilation">++plone++myproject.site/style.min.css</value>
+      <value key="depends">plone</value>
+    </records>
+  </registry>
+```
+
+Registering a js file and a css file in the same bundle is also possible.
+
+```xml 
+<registry>
+  <records interface="plone.base.interfaces.resources.IBundleRegistry" prefix="plone.bundles/css">
+    <value key="enabled">True</value>
+    <value key="csscompilation">++plone++myproject.site/style.min.css</value>
+    <value key="jscompilation">++plone++myproject.site/javascript.min.js</value>
+    <value key="load_async">False</value> 
+    <value key="load_defer">False</value>
+    <value key="depends">plone</value>
+  </records>
+</registry>
+```
+
 (classic-ui-static-resources-available-attributeslabel)=
 
 ## Available attributes
 
+The following attributes are available for registering a static resource:
+
+`enabled`
+:  Whether the bundle is enabled or not. If it is disabled, the bundle will not be loaded.
+
+`jscompilation`
+:  The path to the compiled js file.
+
+`csscompilation`
+:  The path to the compiled css file.
+
+`depends`
+:  A list of bundles that this bundle depends on.
+
+`load_async`
+:  Whether the bundle should be loaded asynchronously or not. *Only JS*
+
+`load_defer`
+:  Whether the bundle should be loaded deferred or not. *Only JS*
+
 
 (classic-ui-static-resources-loading-order-label)=
 
 ## Loading order of resources
 
+`depends` is used to define the loading order of resources, by specifying the name of the depending bundle.

docs/conf.py

@@ -57,6 +57,7 @@
     "sphinx.ext.autosummary",  # plone.api
     "sphinx.ext.graphviz",
     "notfound.extension",
+    "sphinxcontrib.video",
 ]
 
 graphviz_output_format = "svg"
@@ -131,16 +132,15 @@
     "volto/developer-guidelines/branch-policy.md",
 ]
 
-html_js_files = [
-    "patch_scrollToActive.js",
-]
+html_js_files = ["patch_scrollToActive.js", "search_shortcut.js"]
 
 html_extra_path = [
     "robots.txt",
 ]
 
 html_static_path = [
     "_static",
+    "volto/_static",
 ]
 
 # -- Options for myST markdown conversion to html -----------------------------
@@ -155,6 +155,7 @@
     #  instead of ```.
     "substitution",  # plone.restapi \
     # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#substitutions-with-jinja2
+    "html_image",
 ]
 
 myst_substitutions = {
@@ -251,6 +252,7 @@
     "use_repository_button": True,
     "use_issues_button": True,
     "use_edit_page_button": True,
+    "search_bar_text": "Search",
     "switcher": {
         "json_url": "/_static/switcher.json",
         "version_match": version,

docs/install/manage-add-ons-packages.md

@@ -147,7 +147,7 @@ make start-backend
 ```
 
 ```{seealso}
-See the [documentation of `mxdev` in its README.rst](https://github.com/mxstack/mxdev/blob/main/README.rst) for complete information.
+See the [documentation of `mxdev` in its README.md](https://github.com/mxstack/mxdev/blob/main/README.md) for complete information.
 ```
 
 

requirements.txt

@@ -17,3 +17,4 @@ sphinxcontrib.httpdomain  # plone.restapi
 sphinxcontrib.httpexample  # plone.restapi
 sphinxext-opengraph
 sphinx-design
+sphinxcontrib-video