Merge branch '6-dev' of github.com:plone/documentation into 6-dev

stevepiercy · stevepiercy · commit c2bc2212ef77 · 2022-04-04T00:40:38.000-07:00
diff --git a/.gitignore b/.gitignore
@@ -11,3 +11,4 @@ pyvenv.cfg
 # symlinked from submodule
 docs/volto
 docs/plone.restapi
+docs/plone.api
diff --git a/.gitmodules b/.gitmodules
@@ -6,3 +6,7 @@
 	path = submodules/plone.restapi
 	url = https://github.com/plone/plone.restapi.git
 	branch = master
+[submodule "submodules/plone.api"]
+	path = submodules/plone.api
+	url = https://github.com/plone/plone.api.git
+	branch = integration-in-plone-docs-6
diff --git a/Makefile b/Makefile
@@ -33,23 +33,33 @@ distclean:  ## Clean docs build directory and Python virtual environment
 	cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/
 	rm -rf ./bin/ ./lib/ ./lib64 ./include ./pyvenv.cfg
 
+
 bin/python:
 	python3 -m venv . || virtualenv --clear --python=python3 .
 	bin/python -m pip install --upgrade pip
 	bin/pip install -r requirements.txt
 
-docs/volto:
+docs/plone.api:
 	git submodule init; \
 	git submodule update; \
-	ln -s ../submodules/volto/docs/source ./docs/volto
+	bin/pip install -e submodules/plone.api[test]; \
+	ln -s ../submodules/plone.api/docs ./docs/plone.api
+	@echo
+	@echo "Documentation of plone.api initialized."
+
+docs/plone.restapi:
+	git submodule init; \
+	git submodule update; \
+	ln -s ../submodules/plone.restapi ./docs/plone.restapi
 
-docs/restapi:
+docs/volto:
 	git submodule init; \
 	git submodule update; \
-	ln -s "../submodules/plone.restapi" "./docs/plone.restapi"
+	ln -s ../submodules/volto/docs/source ./docs/volto
 
 .PHONY: deps
-deps: bin/python docs/volto docs/restapi  ## Create Python virtual environment, install requirements, initialize or update the volto and plone.restapi submodules, and finally create symlinks to the documentation source.
+deps: bin/python docs/volto docs/plone.restapi docs/plone.api ## Create Python virtual environment, install requirements, initialize or update the volto, plone.restapi, and plone.api submodules, and finally create symlinks to the source files.
+
 
 .PHONY: html
 html: deps  ## Build html
@@ -212,10 +222,13 @@ livehtml: deps  ## Rebuild Sphinx documentation on changes, with live-reload in
 .PHONY: netlify
 netlify:
 	pip install -r requirements.txt
+	pip install -r requirements-netlify.txt
 	git submodule init; \
 	git submodule update; \
+	pip install -e submodules/plone.api[test]; \
 	ln -s ../submodules/volto/docs/source ./docs/volto
-	ln -s "../submodules/plone.restapi" "./docs/plone.restapi"
+	ln -s ../submodules/plone.restapi ./docs/plone.restapi
+	ln -s ../submodules/plone.api/docs ./docs/plone.api
 	cd $(DOCS_DIR) && sphinx-build -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	make storybook
 
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -3,6 +3,8 @@
   --pst-icon-clipboard-list: '\f46d';
   --pst-icon-admonition-todo: var(--pst-icon-clipboard-list);
   --pst-color-admonition-todo:  161 , 46, 233;
+  --target-color: #b9ee9e;
+  --codeblock-color: #aad993;
 }
 
 .visuallyhidden {
@@ -54,7 +56,7 @@ p.ploneorglink img {
 dt:target,
 span.highlighted,
 ul.search li span.highlighted {
-  background-color: #7ddf4493;
+  background-color: var(--target-color);
 }
 
 .bd-sidebar .nav ul {
@@ -125,6 +127,9 @@ div.admonition.admonition-todo > .admonition-title::before {
   color: rgba(var(--pst-color-admonition-todo),1);
   content: var(--pst-icon-admonition-todo);
 }
+.admonition-github-only.admonition {
+  display: none;
+}
 
 
 .topic {
@@ -299,3 +304,31 @@ span.guilabel, span.menuselection {
   font-style: italic;
   white-space: nowrap;
 }
+
+
+/*
+ * extensions
+ */
+
+/* definitions */
+dl.py.function {
+  margin-bottom: 5rem;
+}
+dl.py.function > dt {
+  background-color: var(--codeblock-color);
+  padding: 4px 5px;
+}
+dl.py.function > dt:target {
+  background-color: var(--target-color);  
+}
+dl.field-list > dt {
+  padding-left: 0;
+}
+
+/* code blocks */
+div.viewcode-block:target {
+  padding: 10px 10px;
+  background-color: var(--codeblock-color);
+  border-top: 1px solid var(--codeblock-color);
+  border-bottom: 1px solid var(--codeblock-color);
+}
diff --git a/docs/_static/searchtools.js b/docs/_static/searchtools.js
@@ -254,6 +254,12 @@ var Search = {
 
     function _getBreadcrumbs(item, linkUrl) {
       let parentTitles = item[6];
+      let ploneApiTitles = [
+        "A Plone API",
+        "List of all API methods with descriptions"
+      ];
+      // ugly hack for plone.api documentation integrated via git submodule
+      parentTitles = Array.isArray(parentTitles) ? parentTitles : ploneApiTitles;      
       let path = item[0].split('/')
         .slice(0, -1);
       path = path.map((el, index) => {
diff --git a/docs/_templates/search.html b/docs/_templates/search.html
@@ -78,6 +78,7 @@ <h1 id="search-documentation">{{ _('Search') }}</h1>
           {% for id, title in
             [
               ["backend","Backend"],
+              ["plone.api","plone.api"],
               ["classic-ui","Classic UI"],
               ["volto","Frontend"],
               ["contributing","Contributing"],
diff --git a/docs/backend/index.md b/docs/backend/index.md
@@ -26,7 +26,7 @@ security
 workflows
 search
 zodb
-plone-api
+../plone.api/index.rst
 plone-restapi
 sending-email
 upgrading/index
diff --git a/docs/backend/plone-api.md b/docs/backend/plone-api.md
diff --git a/docs/conf.py b/docs/conf.py
@@ -52,6 +52,9 @@
     "sphinxcontrib.httpexample",
     "sphinxcontrib.spelling",
     "sphinxext.opengraph",
+    # plone.api
+    'sphinx.ext.viewcode',
+    'sphinx.ext.autosummary',
 ]
 
 
diff --git a/docs/contributing/index.md b/docs/contributing/index.md
@@ -63,14 +63,15 @@ See {doc}`setup-build` for instructions for how to set up and build the document
 Contributions are managed through git repositories on GitHub.
 
 - [documentation](https://github.com/plone/documentation)
+- [plone.api](https://github.com/plone/plone.api)
 - [plone.restapi](https://github.com/plone/plone.restapi)
 - [volto](https://github.com/plone/volto)
 
 First discuss whether you should perform any work.
 Any method below is acceptable, but are listed in order of most likely to get a response.
 
-- Search for open issues in [`documentation`](https://github.com/plone/documentation/issues), [`plone.restapi`](https://github.com/plone/plone.restapi/issues), or [`volto`](https://github.com/plone/volto/issues) and comment on them.
-- Create a new issue in [`documentation`](https://github.com/plone/documentation/issues), [`plone.restapi`](https://github.com/plone/plone.restapi/issues), or [`volto`](https://github.com/plone/volto/issues).
+- Search for open issues in [`documentation`](https://github.com/plone/documentation/issues), [`plone.api`](https://github.com/plone/plone.api/issues), [`plone.restapi`](https://github.com/plone/plone.restapi/issues), or [`volto`](https://github.com/plone/volto/issues) and comment on them.
+- Create a new issue in [`documentation`](https://github.com/plone/documentation/issues), [`plone.api`](https://github.com/plone/plone.api/issues), [`plone.restapi`](https://github.com/plone/plone.restapi/issues), or [`volto`](https://github.com/plone/volto/issues).
 - Discuss during conferences, trainings, and other Plone events.
 - Ask on the [Plone Community Forum, Documentation topic](https://community.plone.org/c/documentation/13).
 - Ask in the [Plone chat on Discord](https://discord.com/invite/zFY3EBbjaj).
@@ -111,14 +112,14 @@ Quick edits for minor issues, such as typographical errors, misspellings, and En
 For large edits, first follow the instructions in {doc}`setup-build`.
 
 Once you have your environment set up, then you can follow the standard practice for making a pull request.
-This practice differs depending on whether you are making contributions to only the core `documentation` files, or `plone.restapi` and `volto` files as well.
+This practice differs depending on whether you are making contributions to only the core `documentation` files, or `plone.api`, `plone.restapi` and `volto` files as well.
 
 
 (contributing-documentation-only-label)=
 
 ### Working with only the `plone/documentation` repository
 
-This section describes how to make contributions to files in the `plone/documentation` repository only, and excludes files in `submodules/plone.restapi/docs` and `submodules/volto/docs`.
+This section describes how to make contributions to files in the `plone/documentation` repository only, and excludes files in `submodules/plone.api/docs`, `submodules/plone.restapi/docs` and `submodules/volto/docs`.
 
 1.  From the project root directory, sync your local `6-dev` branch with its remote.
     You might need to resolve conflicts.
@@ -176,11 +177,11 @@ This section describes how to make contributions to files in the `plone/document
 ### Editing external package documentation
 
 If you want to edit documentation of imported external packages, the process is slightly different.
-We use git submodules to manage multiple repositories.
+We use `git submodules` to manage multiple repositories.
 We imported the external repositories the `plone/documentation` repository as described in {doc}`setup-build`.
 
 ```{important}
-We currently use the branches `plone/documentation@6-dev`, `plone/plone.restapi@master`, and `plone/volto@master` as the main branches for developing Plone 6 Documentation.
+We currently use the branches `plone/documentation@6-dev`, `plone/plone.api@integration-in-plone-docs-6`, `plone/plone.restapi@master`, and `plone/volto@master` as the main branches for developing Plone 6 Documentation.
 These branches may change as we get closer to a production release.
 ```
 
@@ -195,7 +196,8 @@ These branches may change as we get closer to a production release.
 1.  Change your working directory to the imported package's directory under `submodules/`.
 
     ```shell
-    # choose one
+    # Choose one.
+    cd submodules/plone.api
     cd submodules/plone.restapi
     cd submodules/volto
     ```
@@ -206,10 +208,13 @@ These branches may change as we get closer to a production release.
     ```shell
     git submodule update
 
-    # For plone.restapi
+    # for plone.api
+    git checkout integration-in-plone-docs-6
+
+    # for plone.restapi
     git checkout master
 
-    # For volto
+    # for volto
     git checkout master
 
     git pull
@@ -246,11 +251,15 @@ These branches may change as we get closer to a production release.
     ```shell
     cd ../..
 
-    # For plone.restapi
+    # for plone.api
+    git add submodules/plone.api
+    git commit -m "Update submodules/plone.api tip"
+
+    # for plone.restapi
     git add submodules/plone.restapi
     git commit -m "Update submodules/plone.restapi tip"
 
-    # For volto
+    # for Volto
     git add submodules/volto
     git commit -m "Update submodules/volto tip"
 
diff --git a/requirements-netlify.txt b/requirements-netlify.txt
@@ -0,0 +1 @@
+plone-autoform<=1.99
diff --git a/submodules/plone.api b/submodules/plone.api
@@ -0,0 +1 @@
+Subproject commit be4005032e68a7711b8bb12f84a8252dbf0fbd5c
diff --git a/submodules/volto b/submodules/volto
@@ -1 +1 @@
-Subproject commit ed2b452242787d83474937d05be0ba1676d5cf73
+Subproject commit 13e90f1f29e94b449c1e38ab811bf43392796148

Original file line number	Diff line number	Diff line change
`@@ -78,6 +78,7 @@ <h1 id="search-documentation">{{ _('Search') }}</h1>`
`78`	`78`	`{% for id, title in`
`79`	`79`	`[`
`80`	`80`	`["backend","Backend"],`
	`81`	`+ ["plone.api","plone.api"],`
`81`	`82`	`["classic-ui","Classic UI"],`
`82`	`83`	`["volto","Frontend"],`
`83`	`84`	`["contributing","Contributing"],`
Original file line number	Diff line number	Diff line change
`@@ -52,6 +52,9 @@`
`52`	`52`	`"sphinxcontrib.httpexample",`
`53`	`53`	`"sphinxcontrib.spelling",`
`54`	`54`	`"sphinxext.opengraph",`
	`55`	`+ # plone.api`
	`56`	`+ 'sphinx.ext.viewcode',`
	`57`	`+ 'sphinx.ext.autosummary',`
`55`	`58`	`]`
`56`	`59`
`57`	`60`