Address review from @gforcada on the testing API reference

- Sort sphinx-autodoc2 into requirements.txt.
- Make the autodoc2 conf.py comments generic instead of naming a specific
  consumer, which would outdate.
- Name the two packages explicitly in the chapter index instead of 'both
  packages'.
- Clarify defaultBases vs the bases argument (class default vs the
  instantiation-time exception) rather than listing them as equivalent.
- Highlight the pytest alternative in the install how-to as a tip.
- Name Blicca (formerly Classic UI) and link the Volto testing docs in the
  test-browser how-to.

Kept the reference intro as prose rather than a third admonition, per the
Plone docs guidance to use admonitions sparingly.

Author: jensens

docs/conf.py

@@ -45,7 +45,7 @@
 extensions = [
     "myst_parser",
     "notfound.extension",
-    "autodoc2",  # developer-guide/testing plone.app.testing reference (static, no import)
+    "autodoc2",  # static API docs from source, no package import needed
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",  # plone.api
     "sphinx.ext.doctest",  # plone.api
@@ -302,10 +302,10 @@
 # Don't show class signature with the class' name.
 autodoc_class_signature = "separated"
 
-# -- Options for autodoc2 (plone.app.testing reference) -----------------------
+# -- Options for autodoc2 -----------------------------------------------------
 # autodoc2 analyses the source statically, so no package import and no Plone
-# installation are needed. It reads the plone.app.testing submodule directly.
-# The ``module`` key gives the namespace package its full dotted name.
+# installation are needed. It reads the package submodules directly.
+# The ``module`` key gives each namespace package its full dotted name.
 autodoc2_packages = [
     {
         "path": "../submodules/plone.app.testing/src/plone/app/testing",

docs/developer-guide/testing/drive-the-test-browser.md

@@ -15,7 +15,8 @@ This guide shows you how to write an end-to-end functional test that drives Plon
 
 ```{important}
 `zope.testbrowser` runs entirely in Python and does **not** run JavaScript.
-Use it for server-rendered pages (Classic UI). To test a Volto frontend, use the Volto documentation's end-to-end testing tools instead.
+Use it for server-rendered pages (Blicca, the frontend formerly called Classic UI).
+To test a Volto frontend, see [Test add-ons](/volto/development/add-ons/test-add-ons-19) instead.
 ```
 
 You need a **functional** layer, either `PLONE_FUNCTIONAL_TESTING` or your own layer built with `FunctionalTesting`.

docs/developer-guide/testing/how-testing-layers-work.md

@@ -50,8 +50,10 @@ This is how a functional layer can, for example, replace the database with a san
 
 ## Layers compose through bases
 
-A layer declares its bases—the layers it builds on—through `defaultBases` or the `bases` argument.
-The test runner sets up each base once, in order, before the layer itself, and reuses an already-set-up base rather than building it again.
+A layer declares its bases—the layers it builds on.
+When you write a reusable layer class, you set them as the `defaultBases` class attribute.
+When you instantiate a layer directly to combine existing ones, you pass them as the `bases` argument instead; that is the exception, not the rule.
+Either way, the test runner sets up each base once, in order, before the layer itself, and reuses an already-set-up base rather than building it again.
 
 The result is a tree of layers, each built once.
 A typical add-on's stack looks like this:

docs/developer-guide/testing/install-add-ons-in-tests.md

@@ -16,7 +16,9 @@ This guide shows you how to install a GenericSetup profile or an add-on inside a
 It uses the helpers from {doc}`testing-api-reference`.
 The examples assume a layer whose fixture already loaded your add-on's ZCML—see {doc}`write-a-testing-layer`.
 
+```{tip}
 If you use pytest, {doc}`pytest-plone </developer-guide/testing/pytest>` also offers an `installer` fixture and an `@pytest.mark.portal(profiles=[...])` marker that do the same thing with less boilerplate.
+```
 
 ## Apply a profile
 

docs/developer-guide/testing/testing-api-reference.md

@@ -17,7 +17,7 @@ Technical reference for Plone's testing API, drawn from two packages:
 - [plone.testing](https://github.com/plone/plone.testing): the underlying layer model and the Zope-level tools.
 
 You import from whichever package a symbol lives in, but from a test author's point of view they are one toolkit, so this page is organized by task rather than by package.
-Each symbol is documented at its canonical location; re-exports are noted.
+Each symbol is documented at its canonical location; where one package re-exports a symbol from the other, that is noted.
 
 To use these to write a `testing.py`, see {doc}`write-a-testing-layer`.
 For the model behind them, see {doc}`how-testing-layers-work`.

requirements.txt

@@ -2,6 +2,7 @@ linkify-it-py
 plone-sphinx-theme<2
 sphinx<9  # See https://github.com/plone/documentation/issues/2037
 sphinx-autobuild
+sphinx-autodoc2
 sphinx-copybutton
 sphinx-design  # Documentation only
 sphinx-examples
@@ -17,4 +18,3 @@ sphinxcontrib-youtube
 sphinxext-opengraph
 sphinxcontrib.mermaid
 vale
-sphinx-autodoc2  # developer-guide/testing plone.app.testing reference

styles/config/vocabularies/Plone/accept.txt

@@ -9,6 +9,7 @@ APIs
 backport(ed|ing)
 Barceloneta
 [Bb]oolean
+Blicca
 bugfix
 [Bb]uildout
 cacheable