Merge pull request plone#1277 from plone/installation-from-source-review

Installation from source review

Author: stevepiercy

docs/_static/custom.css

@@ -47,6 +47,7 @@ img {
 }
 
 figure img,
+img.figure,
 .figure img {
   box-shadow: 0 6px 24px 0 rgba(153, 153, 153, 0.3);
 }
@@ -126,22 +127,6 @@ div.section div.section div.section {
   margin-bottom: 1.5rem !important;
 }
 
-.admonition.toggle .admonition-title {
-  cursor: pointer;
-  display: flex;
-}
-
-.admonition.toggle .admonition-title::after {
-  content: "\f105";
-  font-weight: 900;
-  font-family: "Font Awesome 5 Free";
-  margin-left: auto;
-}
-
-.admonition.toggle .admonition-title.open::after {
-  content: "\f107";
-}
-
 /* admonition todo */
 .admonition.admonition-todo,
 div.admonition.admonition-todo {

docs/_static/plone-home-page.png

@@ -11,13 +11,6 @@
             if ($.trim($(".topbar-contents .bd-toc").html()) === "") {
                 $(".topbar-contents .bd-toc").css("visibility", "hidden");
             }
-            // Add toggle to exercise solutions (admonition with class 'toggle')
-            $(".toggle > *").hide();
-            $(".toggle .admonition-title").show();
-            $(".toggle .admonition-title").click(function() {
-                $(this).parent().children().not(".admonition-title").toggle(400);
-                $(this).parent().children(".admonition-title").toggleClass("open");
-            })
         });
     </script>
 

docs/_static/plone-login-page.png

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

docs/_templates/page.html

@@ -47,6 +47,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
     "sphinx_copybutton",
+    "sphinx_design",
     "sphinx_sitemap",
     "sphinxcontrib.httpdomain",  # plone.restapi
     "sphinxcontrib.httpexample",  # plone.restapi
@@ -84,6 +85,7 @@
     r"https://github.com/plone/plone.docker#for-basic-usage",
     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/plone/volto/issues/new/choose",
     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

docs/backend/index.md

@@ -235,15 +235,13 @@ Using {term}`React` makes frontends fun again!
 Using {term}`React` makes frontends fun again!
 
 
-#### Toggle paragraph (Exercise solution / FAQ)
+#### Nesting directives
 
-Text snippets can be hidden with the option to show. Wrap it in an `admonition` and add the `class` `toggle`.
+You can [nest directives](https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html#nesting-directives), such as [admonitions](https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html#admonitions) and code blocks, by ensuring that the backtick-lines corresponding to the outermost directive are longer than the backtick-lines for the inner directives.
 
 `````
-````{admonition} f-strings can make your life easier
-:class: toggle
-
-To use formatted string literals, begin a string with `f` or `F` before the opening quotation mark or triple quotation mark.
+````{tip}
+To use formatted string literals ("f-strings"), begin a string with `f` or `F` before the opening quotation mark or triple quotation mark.
 Inside this string, you can write a Python expression between `{` and `}` characters that can refer to variables or literal values.
 
 ```{code-block} python
@@ -257,14 +255,10 @@ print(f"my {a}nd line")
 ````
 `````
 
-You can [nest directives](https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html#nesting-directives), such as admonitions and code blocks, by ensuring that the backtick-lines corresponding to the outermost directive are longer than the backtick-lines for the inner directives.
-
 This would be rendered as:
 
-````{admonition} f-strings can make your life easier
-:class: toggle
-
-To use formatted string literals, begin a string with `f` or `F` before the opening quotation mark or triple quotation mark.
+````{tip}
+To use formatted string literals ("f-strings"), begin a string with `f` or `F` before the opening quotation mark or triple quotation mark.
 Inside this string, you can write a Python expression between `{` and `}` characters that can refer to variables or literal values.
 
 ```{code-block} python
@@ -278,6 +272,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/conf.py

@@ -25,9 +25,12 @@ CMS
     Content Management System
 
 Cookiecutter
-    A command-line utility that creates projects from cookiecutters (project templates), e.g. creating a Python package project from a Python package project template.
+    A command-line utility that creates projects from cookiecutters (project templates), for example, creating a Python package project from a Python package project template.
     [See Cookiecutter's documentation](https://cookiecutter.readthedocs.io/en/stable/).
 
+cookiecutter-plone-starter
+    [cookiecutter-plone-starter](https://github.com/collective/cookiecutter-plone-starter/) is a framework for jumpstarting Plone 6 projects quickly.
+
 cookiecutter-zope-instance
     [cookiecutter-zope-instance](https://github.com/plone/cookiecutter-zope-instance) is a cookiecutter template to create a full and complex configuration of a Zope WSGI instance.
 
@@ -48,7 +51,7 @@ Linode
     [Linode.com](https://www.linode.com/) is an American privately owned virtual private server provider company based in Galloway, New Jersey, United States.
 
 mxdev
-    [mxdev](https://github.com/mxstack/mxdev) [mɪks dɛv] is a utility that makes it easy to work with Python projects containing lots of packages, of which you only want to develop some.
+    [mxdev](https://github.com/mxstack/mxdev) [mɪks dɛv] is a utility that makes it easy to work with Python projects containing lots of packages, and you want to develop only some of those packages.
     It is designed for developers who use stable version constraints, then layer their customizations on top of that base while using a version control system.
     This design allows developers to override their base package constraints with a customized or newer version.
 
@@ -69,7 +72,9 @@ pm2
     [PM2](https://pm2.keymetrics.io/) is a daemon process manager.
 
 REST API
-    TODO REST API in general. TODO REST API of Plone.
+    ```{todo}
+    REST API in general. REST API of Plone.
+    ```
 
 S3
     [Amazon Web Services S3](https://aws.amazon.com/s3/).
@@ -345,8 +350,8 @@ Slate
     [Slate.js](https://docs.slatejs.org/) is a highly customizable platform for creating rich-text editors, also known as `WYSIWYG` editors.
     It enables you to create powerful, intuitive editors similar to those you've probably used in Medium, Dropbox Paper, or Google Docs.
 
-volto-slate
-    `volto-slate` is an interactive default text editor for Volto, developed on top of {term}`Slate` while offering enhanced WYSIWYG functionality and behavior.
+`volto-slate`
+    `volto-slate` is an interactive default text editor for Volto, developed on top of {term}`Slate`, offering enhanced WYSIWYG functionality and behavior.
 
 elementEditor
     A generic {term}`volto-slate` plugin architecture that can be used to create other editor interactions that follow the pattern of having a button that toggles a format (an inline element).
@@ -438,4 +443,11 @@ ZODB
 
 Zope
     [Zope](https://zope.readthedocs.io/en/latest/) is a Python-based application server for building secure and highly scalable web applications.
+
+Make
+make
+    [GNU Make](https://www.gnu.org/software/make/) is a tool which controls the generation of executables and other non-source files of a program from the program's source files.
+
+    Make gets its knowledge of how to build your program from a file called the _makefile_, which lists each of the non-source files and how to compute it from other files.
+    When you write a program, you should write a makefile for it, so that it is possible to use Make to build and install the program.
 ```

docs/contributing/writing-docs-guide.md

@@ -34,10 +34,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/glossary.md

@@ -11,65 +11,95 @@ myst:
 
 # 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.
+
+-   [Plone 6 with Volto frontend](https://6.demo.plone.org/)
+-   [Plone 6 Classic UI (nightly build)](https://6-classic.demo.plone.org/en)
+-   [Plone 5.2.x (stable) with Barceloneta frontend](https://demo.plone.org/)
+:::
 
--   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}`source` (contribute to Plone packages, develop add-ons, or install Plone with full control)
+:::{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](install-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 Explanation when to choose which installation method: container vs installation from its packages. Combination for backend and frontend?
+Developers may choose to install Plone from either [the official container images](containers/index) or [packages](install-from-packages).
 
-Developers may choose to install Plone from either [the official container images](containers/index) or [source](source).
+
+### 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.
 
-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.
-This method takes longer.
-It might be a challenge if you bump up against system requirements, or need to resolve conflicts between required packages.
+:::{card}
+:link: containers/index
+:link-type: any
+{octicon}`container;1.5em;sd-mr-1` [Use containers to install Plone](containers/index)
+:::
 
-```{todo}
-Perhaps merge the subsequent section into this section?
-```
 
+### Packages
+
+There may be some cases where using a Plone 6 image and containers is not practical or desired.
+
+-   You use an SQL database that is not PostgreSQL.
+-   You develop custom applications, themes, and add-ons for Plone.
+-   You use a deployment workflow that has specific requirements.
+
+For these situations, Plone 6 may be installed from its packages.
+
+It might be a challenge if you bump up against system requirements, or need to resolve conflicts between required packages.
 
-(install-index-caveat-label)=
+This method takes longer than using containers.
 
-## Caveat that Plone is a large project and source installs are non-trivial
+:::{card}
+:link: install-from-packages
+:link-type: any
+{octicon}`package;1.5em;sd-mr-1` [Install Plone from its packages](install-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}`source`
+-   [Container system requirements](install-containers-index-system-requirements-label)
+-   [Packages system requirements](install-packages-system-requirements-label)
 
 
 ```{toctree}
 :maxdepth: 2
 :hidden: true
 
 containers/index
-source
-source-step-by-step
+install-from-packages
+manage-add-ons-packages
 ```