diff --git a/.gitignore b/.gitignore index 82863e71d..7944bc77e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,11 +1,7 @@ # Dependencies -/bin -/include -/lib -/lib64 +/venv # Generated files -pyvenv.cfg /_build /styles/Microsoft /share diff --git a/Makefile b/Makefile index 98e33474b..6d54cdb42 100644 --- a/Makefile +++ b/Makefile @@ -5,10 +5,11 @@ SHELL = bash # You can set these variables from the command line. SPHINXOPTS ?= PAPER ?= +VALEOPTS ?= # Internal variables. -SPHINXBUILD = "$(realpath bin/sphinx-build)" -SPHINXAUTOBUILD = "$(realpath bin/sphinx-autobuild)" +SPHINXBUILD = "$(realpath venv/bin/sphinx-build)" +SPHINXAUTOBUILD = "$(realpath venv/bin/sphinx-autobuild)" DOCS_DIR = ./docs/ BUILDDIR = ../_build PAPEROPT_a4 = -D latex_paper_size=a4 @@ -29,20 +30,25 @@ clean: ## Clean docs build directory cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/ .PHONY: distclean -distclean: ## Clean docs build directory and Python virtual environment +distclean: ## Clean docs build directory and Python virtual environment, then install requirements cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/ - rm -rf ./bin/ ./lib/ ./lib64 ./include ./pyvenv.cfg - + python3 -m venv venv --clear + venv/bin/pip install -r requirements-initial.txt + venv/bin/pip install -r requirements.txt + @echo + @echo "Installation of requirements completed." -bin/python: - python3 -m venv . - bin/pip install -r requirements-initial.txt - bin/pip install -r requirements.txt +venv/bin/python: ## Setup up Python virtual environment and install requirements + python3 -m venv venv + venv/bin/pip install -r requirements-initial.txt + venv/bin/pip install -r requirements.txt + @echo + @echo "Installation of requirements completed." docs/plone.api: git submodule init; \ git submodule update; \ - bin/pip install -e submodules/plone.api/"[test]"; \ + venv/bin/pip install -e submodules/plone.api/"[test]"; \ ln -s ../submodules/plone.api/docs ./docs/plone.api @echo @echo "Documentation of plone.api initialized." @@ -62,7 +68,7 @@ docs/volto: @echo "Documentation of volto initialized." .PHONY: deps -deps: bin/python docs/volto docs/plone.restapi docs/plone.api ## Create Python virtual environment, install requirements, initialize or update the volto, plone.restapi, and plone.api submodules, and finally create symlinks to the source files. +deps: venv/bin/python docs/volto docs/plone.restapi docs/plone.api ## Create Python virtual environment, install requirements, initialize or update the volto, plone.restapi, and plone.api submodules, and finally create symlinks to the source files. .PHONY: html @@ -196,8 +202,8 @@ linkcheckbroken: deps ## Run linkcheck and show only broken links .PHONY: vale vale: deps ## Run Vale style, grammar, and spell checks - bin/vale sync - bin/vale --no-wrap $(VALEFILES) + venv/bin/vale sync + venv/bin/vale --no-wrap $(VALEOPTS) $(VALEFILES) @echo @echo "Vale is finished; look for any errors in the above output." diff --git a/docs/admin-guide/index.md b/docs/admin-guide/index.md index cf15440e2..cfd1fd152 100644 --- a/docs/admin-guide/index.md +++ b/docs/admin-guide/index.md @@ -11,7 +11,7 @@ myst: # Admin guide -In this part of the documentation, you can find how to install, operate, configure, and deploy Plone. +In this part of the documentation, you can find how to install, operate, and configure Plone. ```{toctree} diff --git a/docs/admin-guide/install-buildout.md b/docs/admin-guide/install-buildout.md index f0f87cc2e..2cd5c586f 100644 --- a/docs/admin-guide/install-buildout.md +++ b/docs/admin-guide/install-buildout.md @@ -25,7 +25,7 @@ For other installation options, see {ref}`get-started-install-label`. ## Prerequisites for installation - 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". +% 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} @@ -47,15 +47,17 @@ cd /plone Create a Python virtual environment. ```shell -python3 -m venv . +python3 -m venv venv ``` Install the minimal Python packages needed in order to run Buildout. ```shell -bin/pip install -r https://dist.plone.org/release/6-latest/requirements.txt +venv/bin/pip install -r https://dist.plone.org/release/6-latest/requirements.txt ``` + + Create a {file}`buildout.cfg` file in your directory with the following contents. ```cfg @@ -75,6 +77,12 @@ eggs = Plone ``` +Use Buildout's [`bootstrap` command](https://www.buildout.org/en/latest/topics/bootstrapping.html) to install a local `buildout` script in the {file}`bin` directory. + +```shell +venv/bin/buildout bootstrap +``` + Run Buildout. ```shell @@ -83,6 +91,7 @@ bin/buildout This may take a few minutes. +Whenever you change the Buildout configuration, run `./bin/buildout` again. ## Start Plone in foreground mode diff --git a/docs/admin-guide/install-pip.md b/docs/admin-guide/install-pip.md index 62ede6906..cb8aad8de 100644 --- a/docs/admin-guide/install-pip.md +++ b/docs/admin-guide/install-pip.md @@ -25,7 +25,7 @@ For other installation options, see {ref}`get-started-install-label`. ## Prerequisites for installation - 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". +% 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} @@ -47,13 +47,13 @@ cd /plone Create a Python virtual environment. ```shell -python3 -m venv . +python3 -m venv venv ``` 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 +venv/bin/pip install -c https://dist.plone.org/release/6.0-latest/constraints.txt Plone pipx ``` diff --git a/docs/admin-guide/run-plone.md b/docs/admin-guide/run-plone.md index d90e363be..66eb6ed30 100644 --- a/docs/admin-guide/run-plone.md +++ b/docs/admin-guide/run-plone.md @@ -19,6 +19,7 @@ There are different commands to run Plone, depending on which method you used to Running Plone in foreground mode will show output in the terminal. This is recommended while developing a Plone site. +The command you use depends on the installation method you used. Cookieplone: : ```shell diff --git a/docs/backend/search.md b/docs/backend/search.md index 318453e55..5e25aadc2 100644 --- a/docs/backend/search.md +++ b/docs/backend/search.md @@ -1,16 +1,30 @@ --- myst: html_meta: - "description": "" - "property=og:description": "" - "property=og:title": "" - "keywords": "" + "description": "How to index and search content in Plone" + "property=og:description": "How to index and search content in Plone" + "property=og:title": "Search" + "keywords": "Plone, search, index, querystring, catalog" --- (backend-search-label)= # Search +To index and search content in Plone, see the Plone 5 documentation {doc}`plone5:develop/plone/searching_and_indexing/index`. + +Alternatively, you can integrate any open source search engine with your Plone site. + +- [Solr](https://solr.apache.org/) - See the add-on [`collective.solr`](https://github.com/collective/collective.solr) and its [documentation](https://collectivesolr.readthedocs.io/en/latest/). +- [`collective.elasticsearch`](https://github.com/collective/collective.elasticsearch) +- [`collective.elastic.plone`](https://github.com/collective/collective.elastic.plone) + +You can find a comprehensive list of search options in [Awesome Plone - Searching and Categorizing](https://github.com/collective/awesome-plone?tab=readme-ov-file#searching-and-categorizing) + + +```{todo} +Help us [Migrate content from v5 "Queries, Search And Indexing" #1730](https://github.com/plone/documentation/issues/1730). +``` (backend-search-catalog-label)= diff --git a/docs/conceptual-guides/compare-buildout-pip.md b/docs/conceptual-guides/compare-buildout-pip.md new file mode 100644 index 000000000..af770a706 --- /dev/null +++ b/docs/conceptual-guides/compare-buildout-pip.md @@ -0,0 +1,38 @@ +--- +myst: + html_meta: + "description": "Compare Plone Classic UI's installation tools, Buildout and pip" + "property=og:description": "Compare Plone Classic UI's installation tools, Buildout and pip" + "property=og:title": "Compare Buildout and pip" + "keywords": "Plone 6, Conceptual guides, Classic UI, Buildout, pip, install" +--- + +# Compare Buildout and pip + +This guide explains the differences between two tools, {term}`Buildout` and {term}`pip`, to install Plone and its Classic UI user interface, helping to inform your choice when developing your new project in Plone. + +The choice of installation tool has implications for admins and developers. + +````{grid} 1 1 1 2 +:gutter: 1 +:margin: 0 +:padding: 0 + +```{grid-item-card} Buildout +- You can create recipes to automate development and production installations. +- Maintained and used primarily by the small Plone community. +- May have problems resolving dependencies when a new pip or setuptools version is released. +- Source checkouts managed through {term}`mr.developer`. +``` + +```{grid-item-card} pip +- Installs or uninstalls packages only. +- Maintained and used by the large Python community. +- Changes in dependency resolution are well-documented. +- Source checkouts managed through {term}`mxdev`. +``` +```` + +```{seealso} +[Proposal: Use pip constraints as canonical version location #3670](https://github.com/plone/Products.CMFPlone/issues/3670) +``` \ No newline at end of file diff --git a/docs/glossary.md b/docs/glossary.md index ed4b20897..83da720e1 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -296,6 +296,9 @@ TC39 They established a [process](https://tc39.es/process-document/) where the proposals are discussed, developed, and eventually approved (or dropped). The process has five Stages (0 to 4) where reaching the Stage 4 means the proposal is finished, and it becomes part of the JavaScript specification. +`mr.developer` + [`mr.developer`](https://pypi.org/project/mr.developer/) is a {term}`Buildout` extension that makes it easy to work with buildouts containing lots of packages, where you only want to develop a few of them. + `mrs-developer` Also called "missdev", a tool similar to buildout's `mr.developer`. It automatically downloads and keeps up to date copies of software and add-ons under development based on definitions stored in `mrs.developer.json`. diff --git a/docs/install/containers/index.md b/docs/install/containers/index.md index 0d75813d8..52aa0d809 100644 --- a/docs/install/containers/index.md +++ b/docs/install/containers/index.md @@ -45,9 +45,9 @@ Although there are many container engine tools for developing, managing, and run The system requirements include those required by Docker itself. -- [Linux](https://docs.docker.com/desktop/install/linux/) -- [macOS](https://docs.docker.com/desktop/install/mac-install/) -- [Windows](https://docs.docker.com/desktop/install/windows-install/) +- [Linux](https://docs.docker.com/desktop/setup/install/linux/) +- [macOS](https://docs.docker.com/desktop/setup/install/mac-install/) +- [Windows](https://docs.docker.com/desktop/setup/install/windows-install/) Plone 6 itself requires memory and disk space in addition to those of Docker alone. See its {ref}`install-packages-hardware-requirements-label`. @@ -66,13 +66,13 @@ Docker Desktop includes all Docker tools. First start the Plone Backend, naming it `plone6-backend` and creating a site with its default configuration, using the following command. ```shell -docker run --name plone6-backend -e SITE=Plone -e CORS_ALLOW_ORIGIN='*' -d -p 8080:8080 plone/plone-backend:{PLONE_BACKEND_MINOR_VERSION} +docker run --name plone6-backend -e SITE=Plone -d -p 8080:8080 plone/plone-backend:{PLONE_BACKEND_MINOR_VERSION} ``` Now start the Plone Frontend, linking it to the `plone6-backend`: ```shell -docker run --name plone6-frontend --link plone6-backend:backend -e RAZZLE_API_PATH=http://localhost:8080/Plone -e RAZZLE_INTERNAL_API_PATH=http://backend:8080/Plone -d -p 3000:3000 plone/plone-frontend:latest +docker run --name plone6-frontend --link plone6-backend:backend -e RAZZLE_DEV_PROXY_API_PATH=http://backend:8080/Plone -d -p 3000:3000 plone/plone-frontend:latest ``` diff --git a/docs/install/create-project-cookieplone.md b/docs/install/create-project-cookieplone.md index 465bfbfdc..306412a8e 100644 --- a/docs/install/create-project-cookieplone.md +++ b/docs/install/create-project-cookieplone.md @@ -33,11 +33,16 @@ For other installation options, see {ref}`get-started-install-label`. Plone 6 has both hardware requirements and software prerequisites. +(create-project-cookieplone-hardware-requirements-label)= + ### Hardware requirements ```{include} /_inc/_hardware-requirements.md ``` + +(create-project-cookieplone-prerequisites-for-installation-label)= + ### Prerequisites for installation ```{include} ../volto/contributing/install-operating-system.md @@ -96,6 +101,8 @@ pip install pipx ``` +(create-project-cookieplone-generate-the-project-label)= + ## Generate the project After satisfying the prerequisites and having activated an LTS version of Node, diff --git a/docs/install/index.md b/docs/install/index.md index f3218e913..817999afd 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -41,6 +41,8 @@ https://demo.plone.org/ First, choose a Plone user interface, or frontend. You can read {doc}`/conceptual-guides/choose-user-interface` to help inform your choice between Volto and Classic UI. +If you choose Classic UI, then you can read {doc}`/conceptual-guides/compare-buildout-pip` to help inform your choice between Buildout and pip for an installation method. + Then choose one of the following installation methods. If you are following a [Plone training](https://training.plone.org/), it should specify which option to choose. diff --git a/submodules/plone.restapi b/submodules/plone.restapi index 9f0feffad..4f3bb4f1c 160000 --- a/submodules/plone.restapi +++ b/submodules/plone.restapi @@ -1 +1 @@ -Subproject commit 9f0feffad288f18e5fa3d3f63094614971d1d164 +Subproject commit 4f3bb4f1c656295f609a9aaea4540325d1b55b8e diff --git a/submodules/volto b/submodules/volto index 5d08348bf..4aecd1c86 160000 --- a/submodules/volto +++ b/submodules/volto @@ -1 +1 @@ -Subproject commit 5d08348bf443a67241a995e6c917eadf6d81b1fc +Subproject commit 4aecd1c862f9a2ff42261f3dcc656f287953cedd