Merge pull request plone#1193 from plone/import-restapi

Import plone.restapi docs

Author: stevepiercy

.gitignore

@@ -10,3 +10,4 @@ pyvenv.cfg
 
 # symlinked from submodule
 docs/volto
+docs/plone.restapi

.gitmodules

@@ -2,3 +2,7 @@
 	path = submodules/volto
 	url = https://github.com/plone/volto.git
 	branch = master
+[submodule "submodules/plone.restapi"]
+	path = submodules/plone.restapi
+	url = https://github.com/plone/plone.restapi.git
+	branch = plone6docs

Makefile

@@ -43,8 +43,13 @@ docs/volto:
 	git submodule update; \
 	ln -s ../submodules/volto/docs/source ./docs/volto
 
+docs/restapi:
+	git submodule init; \
+	git submodule update; \
+	ln -s "../submodules/plone.restapi" "./docs/plone.restapi"
+
 .PHONY: deps
-deps: bin/python docs/volto  ## Create Python virtual environment, install requirements, pull in Volto submodule
+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.
 
 .PHONY: html
 html: deps  ## Build html
@@ -210,6 +215,7 @@ netlify:
 	git submodule init; \
 	git submodule update; \
 	ln -s ../submodules/volto/docs/source ./docs/volto
+	ln -s "../submodules/plone.restapi" "./docs/plone.restapi"
 	cd $(DOCS_DIR) && sphinx-build -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	make storybook
 

docs/conf.py

@@ -48,6 +48,8 @@
     "sphinx.ext.todo",
     "sphinx_copybutton",
     "sphinx_sitemap",
+    "sphinxcontrib.httpdomain",
+    "sphinxcontrib.httpexample",
     "sphinxcontrib.spelling",
     "sphinxext.opengraph",
 ]
@@ -67,7 +69,6 @@
 # Options for the linkcheck builder
 # Ignore localhost
 linkcheck_ignore = [
-    # TODO: Before release, clean up any links to ignore
     r"http://localhost",
     r"http://0.0.0.0",
     r"http://127.0.0.1",
@@ -80,6 +81,8 @@
     r"https://github.com/plone/plone.rest#cors",
     r"https://github.com/plone/plone.volto/blob/6f5382c74f668935527e962490b81cb72bf3bc94/src/kitconcept/volto/upgrades.py#L6-L54",
     r"https://github.com/tc39/proposals/blob/HEAD/finished-proposals.md#finished-proposals",
+    r"https://coveralls.io/repos/github/plone/plone.restapi/badge.svg\?branch=master",  # plone.restapi
+    r"https://github.com/plone/plone.restapi/blob/dde57b88e0f1b5f5e9f04e6a21865bc0dde55b1c/src/plone/restapi/services/content/add.py#L35-L61",  # plone.restapi
 ]
 linkcheck_anchors = True
 linkcheck_timeout = 10
@@ -92,6 +95,7 @@
 # The suffix of source filenames.
 source_suffix = {
     ".md": "markdown",
+    ".rst": "restructuredtext",
 }
 
 # The master toctree document.
@@ -103,7 +107,17 @@
 exclude_patterns = [
     "spelling_wordlist.txt",
     "**/CHANGES.rst",
+    "**/CONTRIBUTORS.rst",
     "**/LICENSE.rst",
+    "**/README.rst",
+    "plone.restapi/.*",
+    "plone.restapi/bin",
+    "plone.restapi/docs/source/ideas",
+    "plone.restapi/include",
+    "plone.restapi/lib",
+    "plone.restapi/news",
+    "plone.restapi/performance",
+    "plone.restapi/src",
 ]
 
 html_extra_path = [

docs/contributing/admins.md

@@ -28,9 +28,19 @@ Inside the repository `plone/documentation`, add a git submodule that points to
 git submodule add [email protected]:plone/my_package.git submodules/my_package
 ```
 
+Add a target `docs/my_package` in `Makefile`, then add `docs/my_package` to the `deps` target, following `volto` as a pattern.
+You might need to adjust the paths to your package's documentation after it is cloned.
+
+To complete setup, generate a symlink to your project's docs, and build the docs, use a single command.
+
+```shell
+make html
+```
+
 To make it easier for other contributors to work with your project, update the following files, using `volto` as a model.
 
--   `Makefile` targets  `docs/my_package` and `deps`
--   The documentation section {ref}`contributing-editing-volto-documentation-label`
+-   Add it to the documentation section {ref}`contributing-editing-external-package-documentation-label`.
+-   Add the symlink `docs/my_package` to `.gitignore`.
+-   Optionally set a branch to work on in `.gitmodules`.
 
 Commit and push your changes to a remote, and submit a pull request against [`plone/documentation@6-dev`](https://github.com/plone/documentation/compare).

docs/contributing/index.md

@@ -63,13 +63,14 @@ 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.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) or [`volto`](https://github.com/plone/volto/issues) and comment on them.
-- Create a new issue in [`documentation`](https://github.com/plone/documentation/issues) or [`volto`](https://github.com/plone/volto/issues).
+- 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).
 - 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).
@@ -110,14 +111,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 `volto` files as well.
+This practice differs depending on whether you are making contributions to only the core `documentation` files, or `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 `plone/volto/docs` files.
+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`.
 
 1.  From the project root directory, sync your local `6-dev` branch with its remote.
     You might need to resolve conflicts.
@@ -170,16 +171,16 @@ This section describes how to make contributions to files in the `plone/document
 1.  Members who subscribe to the repository will receive a notification and review your request.
 
 
-(contributing-editing-volto-documentation-label)=
+(contributing-editing-external-package-documentation-label)=
 
-### Editing Volto documentation
+### Editing external package documentation
 
-If you want to edit the Volto documentation — the files within the `docs/volto` subdirectory — the process is slightly different.
+If you want to edit documentation of imported external packages, the process is slightly different.
 We use git submodules to manage multiple repositories.
-We imported the `plone/volto` repository into the `plone/documentation` repository as described in {doc}`setup-build`.
+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` and `plone/volto@master` as the main branches for developing Plone 6 Documentation.
+We currently use the branches `plone/documentation@6-dev`, `plone/plone.restapi@plone6docs`, 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.
 ```
 
@@ -191,40 +192,48 @@ These branches may change as we get closer to a production release.
     git pull
     ```
 
-1.  Change your working directory from the project root directory to `submodules/volto`.
+1.  Change your working directory to the imported package's directory under `submodules/`.
 
     ```shell
+    # choose one
+    cd submodules/plone.restapi
     cd submodules/volto
     ```
 
-1.  Update the submodule, and sync your local `master` branch with its remote.
+1.  Update the submodule, and sync your local development branch with its remote.
     You might need to resolve conflicts.
 
     ```shell
     git submodule update
+
+    # For plone.restapi
+    git checkout plone6docs
+
+    # For volto
     git checkout master
+
     git pull
     ```
 
-1.  Create a new branch from `volto/master`.
+1.  Create a new branch from the development branch.
 
     ```shell
     git checkout -b <new_branch>
     ```
 
-1.  Make edits to files in `docs/volto` using your favorite editor, and save, preview, and test.
+1.  Make edits to files in `docs/<external_package>` using your favorite editor, and save, preview, and test.
     You must run and pass the builds `html` and `linkcheck` without causing new errors.
 
     ```shell
-    # Optionally clean the builds to avoid cache issues
-    # Note that for the Volto docs only, we use "docs-" as a prefix for make targets
-    # because it has so many of them and to avoid a conflict with the core application.
+    # Optionally clean the builds to avoid cache issues.
+    # Note that for the external packages' documentation only,
+    # we use "docs-" as a prefix for make targets to avoid a conflicts.
     make docs-clean
     make docs-html
     make docs-linkcheck
     ```
 
-1.  Back in `submodules/volto`, commit and push your changes to the remote.
+1.  Back in `submodules/<external_package>`, commit and push your changes to the remote.
 
     ```shell
     git add <files>
@@ -236,13 +245,20 @@ These branches may change as we get closer to a production release.
 
     ```shell
     cd ../..
+
+    # For plone.restapi
+    git add submodules/plone.restapi
+    git commit -m "Update submodules/plone.restapi tip"
+
+    # For volto
     git add submodules/volto
     git commit -m "Update submodules/volto tip"
+
     git push
     ```
 
-1.  Visit the GitHub `plone/volto` repository, and [create a pull request](https://github.com/plone/volto/compare) against the branch `master`.
-1.  Members who subscribe to the `plone/volto` repository will receive a notification and review your request.
+1.  Visit the GitHub `plone/<external_package>` repository, and create a pull request against the development branch.
+1.  Members who subscribe to the `plone/<external_package>` repository will receive a notification and review your request.
 
 
 (contributing-code-of-conduct-label)=

docs/index.md

@@ -1,22 +1,25 @@
 ---
 html_meta:
-  "description": ""
-  "property=og:description": ""
-  "property=og:title": ""
-  "keywords": ""
+  "description": "This website is the HTML documentation of Plone, an open source, enterprise-level content management system."
+  "property=og:description": "This website is the HTML documentation of Plone, an open source, enterprise-level content management system."
+  "property=og:title": "Plone 6 Documentation"
+  "keywords": "Plone 6, content management system, CMS, open source, Documentation, Volto, Classic UI, frontend, backend, plone.restapi, plone.api"
 ---
 
 (index-label)=
 
 # Plone 6 Documentation
 
+This website is the HTML documentation of Plone, an open source, enterprise-level content management system.
+
 ```{toctree}
 :maxdepth: 2
 :hidden: true
 
 backend/index
 volto/index
 classic-ui/index
+plone.restapi/docs/source/index
 contributing/index
 ```
 

requirements.txt

@@ -1,6 +1,6 @@
 docutils<0.17,>=0.15  # sphinx-book-theme 0.2.0 has requirement docutils<0.17,>=0.15
 Sphinx
-jsx-lexer
+jsx-lexer  # volto
 lesscpy
 linkify-it-py
 myst-parser
@@ -9,5 +9,7 @@ sphinx-book-theme
 sphinx-copybutton
 sphinx-sitemap
 sphinx-togglebutton
+sphinxcontrib.httpdomain  # plone.restapi
+sphinxcontrib.httpexample  # plone.restapi
 sphinxcontrib-spelling
 sphinxext-opengraph