Overhaul Install index to not suck so hard

Add sphinx-design to requirements
Add sphinx_design to conf.py
Tidy up docs referenced by Install Index
Add Extensions section to writing-docs-guide.md

Author: stevepiercy

docs/backend/index.md

@@ -31,7 +31,7 @@ workflows
 search
 indexing
 zodb
-../plone.api/index.rst
+../plone.api/index
 plone-restapi
 sending-email
 upgrading/index

docs/conf.py

@@ -47,6 +47,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
     "sphinx_copybutton",
+    "sphinx_design",
     "sphinx_sitemap",
     "sphinxcontrib.httpdomain",  # plone.restapi
     "sphinxcontrib.httpexample",  # plone.restapi

docs/contributing/writing-docs-guide.md

@@ -271,6 +271,28 @@ print(f"my {a}nd line")
 ````
 
 
+### Extensions
+
+We use several extensions to enhance the presentation of Plone documentation.
+
+-   [`sphinx.ext.intersphinx`](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html) provides linking between separate projects that use Sphinx for documentation.
+-   [`sphinx.ext.todo`](https://www.sphinx-doc.org/en/master/usage/extensions/todo.html) adds support for todo items.
+-   [`sphinx_copybutton`](https://sphinx-copybutton.readthedocs.io/en/latest/index.html)  adds a little "copy" button to the right of code blocks.
+-   [`sphinx-design`](https://sphinx-design.readthedocs.io/en/latest/) adds grids, cards, icons, badges, buttons, tabs, and dropdowns.
+-   [`sphinx_sitemap`](https://pypi.org/project/sphinx-sitemap/) generates multiversion and multilanguage [sitemaps.org](https://www.sitemaps.org/protocol.html) compliant sitemaps.
+-   [`sphinxcontrib.httpdomain`](https://sphinxcontrib-httpdomain.readthedocs.io/en/stable/) provides a Sphinx domain for describing HTTP APIs.
+    It is used by Plone's {doc}`plone.restapi/docs/source/index`.
+-   [`sphinxcontrib.httpexample`](https://sphinxcontrib-httpexample.readthedocs.io/en/latest/) enhances `sphinxcontrib-httpdomain` by generating RESTful HTTP API call examples for different tools from a single HTTP request example.
+    Supported tools include [curl](https://curl.se/), [wget](https://www.gnu.org/software/wget/), [httpie](https://httpie.io/), and [python-requests](https://requests.readthedocs.io/en/latest/).
+    It is used by Plone's {doc}`plone.restapi/docs/source/index`.
+-   [`sphinxcontrib.spelling`](https://sphinxcontrib-spelling.readthedocs.io/en/latest/) provides spell checking. 
+-   [`sphinxext.opengraph`](https://pypi.org/project/sphinxext-opengraph/) generates [OpenGraph metadata](https://ogp.me/).
+-   [`sphinx.ext.viewcode`](https://www.sphinx-doc.org/en/master/usage/extensions/viewcode.html) generates pages of source code modules and links between the source and the description.
+    It is used by {doc}`/plone.api/index`.
+-   [`sphinx.ext.autosummary`](https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html) generates function/method/attribute summary lists.
+    It is used by {doc}`/plone.api/index`.
+
+
 ## Abridged Plone Documentation Styleguide
 
 Guides should be informational, but friendly.

docs/install/containers/index.md

@@ -33,10 +33,10 @@ Although there are many container engine tools for developing, managing, and run
 
 (install-containers-index-system-requirements-label)=
 
-### System Requirements
+### System requirements
 
 ```{todo}
-Add System Requirements
+Add system requirements
 ```
 
 

docs/install/index.md

@@ -10,61 +10,80 @@ html_meta:
 
 # Install
 
+In this part of the documentation, you can find how to try Plone and how to choose an installation method if you want to develop in Plone.
+
 
 (install-index-getting-started-label)=
 
 ## Getting started
 
-What do you want to do?
+::::{grid} 1 2 2 2
+:gutter: 1 1 1 2
+
+:::{grid-item-card} {octicon}`browser;1.5em;sd-mr-1` Try a demo
+
+Choose a version.
 
--   Try a demo now.
-    -   [Plone 6 with Volto frontend](https://6.demo.plone.org/)
-    -   [Plone 5.2.x with Barceloneta frontend](https://demo.plone.org/)
--   [Run Plone in containers](containers/index) (why use containers here.)
--   {doc}`installation-from-packages` (contribute to Plone packages, develop add-ons, or install Plone with full control)
+-   [Plone 6 with Volto frontend](https://6.demo.plone.org/)
+-   [Plone 6 Classic UI (nightly build)](https://6-classic.demo.plone.org/)
+-   [Plone 5.2.x (stable) with Barceloneta frontend](https://demo.plone.org/)
+:::
+
+:::{grid-item-card} {octicon}`download;1.5em;sd-mr-1` Install
+
+Developers may choose to install Plone from either [the official container images](containers/index) or [packages](installation-from-packages).
++++
+Help me [choose an installation method](install-index-choose-installation-method-label).
+:::
+
+::::
 
 
 (install-index-choose-installation-method-label)=
 
 ## Choose an installation method
 
-```{todo}
-Add an explanation for choosing an installation method: container versus installation from packages.
-Is there a combination for backend and frontend using a cookiecutter?
-```
-
 Developers may choose to install Plone from either [the official container images](containers/index) or [packages](installation-from-packages).
 
+
+### Containers
+
 The Plone 6 container images are compliant with the [Open Container Initiative (OCI)](https://opencontainers.org/).
 They should work with any OCI-compliant container engine for developing, managing, and running Plone 6 images.
 Two popular options include [podman](https://podman.io/) and [Docker](https://www.docker.com/products/docker-desktop/).
 The Plone 6 images have all the system requirements, pre-requisites, and Plone 6 already installed, except those requirements needed for running the container engine itself.
 This option is the quickest method to install and develop for Plone 6 and its packages.
 
+:::{card}
+:link: containers/index
+:link-type: any
+{octicon}`container;1.5em;sd-mr-1` [Use containers to install Plone](containers/index)
+:::
+
+
+### Packages
+
 There may be some cases where using a Plone 6 image is not practical or desired.
 You might want to use an SQL database that is not PostgreSQL, or you might use a deployment workflow that has specific requirements.
-For these situations, Plone 6 may be installed manually.
+For these situations, Plone 6 may be installed from its packages.
 This method takes longer.
 It might be a challenge if you bump up against system requirements, or need to resolve conflicts between required packages.
 
-```{todo}
-Perhaps merge the subsequent section into this section?
-```
-
-
-(install-index-caveat-label)=
-
-## Caveat that Plone is a large project and source installs are non-trivial
+:::{card}
+:link: installation-from-packages
+:link-type: any
+{octicon}`package;1.5em;sd-mr-1` [Install Plone from its packages](installation-from-packages)
+:::
 
 
 (install-index-system-requirements-label)=
 
 ## System Requirements
 
-System requirements depend upon your choice of installation method:
+System requirements depend upon your choice of installation method.
 
--   [Use container images](containers/index)
--   {doc}`installation-from-packages`
+-   [Container system requirements](install-containers-index-system-requirements-label)
+-   [Packages system requirements](install-packages-system-requirements-label)
 
 
 ```{toctree}

requirements.txt

@@ -7,6 +7,7 @@ myst-parser
 sphinx-autobuild
 sphinx-book-theme<=0.3.99
 sphinx-copybutton
+sphinx-design
 sphinx-sitemap
 sphinx-togglebutton
 sphinxcontrib.httpdomain  # plone.restapi