Use an include for creating a Classic UI instance in foreground mode

Author: stevepiercy

docs/_inc/_create-classic-ui-instance.inc

@@ -0,0 +1,15 @@
+
+Your instance starts in foreground mode.
+This should be used only for troubleshooting or local demonstration purposes.
+
+Now you can visit `http://localhost:8080` in your browser.
+Click the button {guilabel}`Create Classic UI Plone site`.
+
+Enter {guilabel}`username` of `admin`, and {guilabel}`password` of `admin`.
+
+Enter values in the form, and click the button {guilabel}`Create Plone Site`.
+
+You will be redirected to your new Classic UI Plone site.
+
+To stop the Plone instance in foreground mode, type {kbd}`CTRL-C`.
+

docs/admin-guide/install-buildout.md

@@ -37,10 +37,11 @@ For other installation options, see {ref}`get-started-install-label`.
 
 ## Installation
 
-Select a directory of your choice.
+Select a directory of your choice, and change it to your working directory.
 
 ```shell
-mkdir -p <my_projects>/plone && cd <my_projects>/plone
+mkdir -p <my_projects>/plone
+cd <my_projects>/plone
 ```
 
 Create a Python virtual environment.
@@ -55,7 +56,7 @@ Install the minimal Python packages needed in order to run Buildout.
 bin/pip install -r https://dist.plone.org/release/6-latest/requirements.txt
 ```
 
-Create a `buildout.cfg` file in your directory with the following contents:
+Create a {file}`buildout.cfg` file in your directory with the following contents.
 
 ```cfg
 [buildout]
@@ -67,6 +68,7 @@ parts =
 
 [instance]
 recipe = plone.recipe.zope2instance
+# user = username:password - Use a secure token in a production environment.
 user = admin:admin
 http-address = 8080
 eggs =
@@ -82,27 +84,16 @@ bin/buildout
 This may take a few minutes.
 
 
-## Run Plone in foreground mode
+## Start Plone in foreground mode
 
 Start the instance for a quick test in foreground mode:
 
 ```shell
 bin/instance fg
 ```
 
-Your instance starts in foreground mode.
-This should be used only for troubleshooting or local demonstration purposes.
-
-Now you can visit `http://localhost:8080` in your browser.
-Select {guilabel}`Create Classic UI Plone site`.
-
-Enter {guilabel}`username` of `admin`, and {guilabel}`password` of `admin`.
-
-Fill out the form as needed, and click {guilabel}`Create Plone Site`.
-
-You will be redirected to your new Plone instance.
-
-To stop the Plone instance in foreground mode, type {kbd}`CTRL-C`.
+```{include} /_inc/_create-classic-ui-instance.inc
+```
 
 
 ## Start Plone as a background service

docs/admin-guide/install-pip.md

@@ -20,45 +20,51 @@ It provides a basic installation without many additional tools to help with deve
 For other installation options, see {ref}`get-started-install-label`.
 ```
 
-## Prerequisites
+(install-pip-prerequisites)=
 
-- Python 3.10 or greater
+## Prerequisites for installation
 
-On Debian-based systems you can install Python with following command:
+-   For Plone 6.0, Python {SUPPORTED_PYTHON_VERSIONS_PLONE60}
+% TODO: These instructions install Plone 6.0.x. Uncomment next line and change the subsequent include when Plone 6.1 is released and "latest". 
+% -   For Plone 6.1, Python {SUPPORTED_PYTHON_VERSIONS_PLONE61}
 
-```shell
-sudo apt install python3.12 python3.12-dev python3.12-venv
+
+### Python
+
+```{include} /_inc/_install-python-plone60.md
 ```
 
+
 ## Installation
 
-Select a directory of your choice:
+Select a directory of your choice, and change it to your working directory.
 
 ```shell
-mkdir -p /opt/plone
-cd /opt/plone
+mkdir -p <my_projects>/plone
+cd <my_projects>/plone
 ```
 
-Create a Python virtual environment:
+Create a Python virtual environment.
 
 ```shell
 python3 -m venv .
 ```
 
-Install Plone and a helper package:
+Install Plone and a helper package, {term}`pipx`.
 
 ```shell
 bin/pip install -c https://dist.plone.org/release/6.0-latest/constraints.txt Plone pipx
 ```
 
+
 ## Create a Zope instance
 
-Create a file `instance.yaml` with the following contents:
+Create a file {file}`instance.yaml` in your directory with the following contents.
 
 ```yaml
-# please change the password to a secure token!
 default_context:
   initial_user_name: "admin"
+# Use a secure token for the password in a production environment.
   initial_user_password: "admin"
   wsgi_listen: "localhost:8080"
   debug_mode: false
@@ -69,20 +75,20 @@ default_context:
   }
 ```
 
-Now run the {term}`cookiecutter` tool to create configuration for a Zope instance:
+Now run the {term}`cookiecutter` tool to create configuration for a Zope instance.
 
 ```
 bin/pipx run cookiecutter -f --no-input --config-file instance.yaml gh:plone/cookiecutter-zope-instance
 ```
 
+
 ## Start Plone in foreground mode
 
-Start the instance for a quick test:
+Start the instance for a quick test.
 
 ```shell
 bin/runwsgi -v instance/etc/zope.ini
 ```
 
-Your instance starts in foreground mode, which is only advisable for troubleshooting or for local demonstration purposes.
-
-Now you can call the url `http://localhost:8080` in your browser and you can add a **Classic UI Plone site**.
+```{include} /_inc/_create-classic-ui-instance.inc
+```

docs/contributing/core/index.md

@@ -124,14 +124,8 @@ Once that's done, you can start an instance of Plone with the following command.
 ./bin/instance fg
 ```
 
-To visit your Plone instance, you can open the link http://0.0.0.0:8080 in a web browser.
-
-You will be presented with several options.
-Click the button {guilabel}`Create Classic UI Plone site`.
-
-Enter values in the form, and click the button {guilabel}`Create Plone Site`.
-
-You will be redirected to your new Classic UI Plone site.
+```{include} /_inc/_create-classic-ui-instance.inc
+```
 
 ```{warning}
 Ignore the warning about accessing the Plone backend through its Classic UI frontend.
@@ -141,11 +135,6 @@ They will not work with buildout.
 To contribute to Volto, you will need to start over, and follow {doc}`../volto`.
 ```
 
-To login, the default credentials are the following.
-
--   username: `admin`
--   password: `admin`
-
 
 (contributing-core-work-with-git-label)=