From 3a0f6389429f82c9089cbc41b7f0296621ed2325 Mon Sep 17 00:00:00 2001 From: Manas Kenge <110519001+Manas-Kenge@users.noreply.github.com> Date: Tue, 8 Apr 2025 00:10:22 +0530 Subject: [PATCH 1/4] add FE & BE commands --- .../cookieplone-make-commands.md | 96 +++++++++++++++++++ docs/reference-guide/index.md | 4 + 2 files changed, 100 insertions(+) create mode 100644 docs/reference-guide/cookieplone-make-commands.md diff --git a/docs/reference-guide/cookieplone-make-commands.md b/docs/reference-guide/cookieplone-make-commands.md new file mode 100644 index 000000000..818eec973 --- /dev/null +++ b/docs/reference-guide/cookieplone-make-commands.md @@ -0,0 +1,96 @@ +--- +myst: + html_meta: + "description": "Cookieplone make commands" + "property=og:description": "Cookieplone make commands" + "property=og:title": "Cookieplone make commands" + "keywords": "Cookieplone, make, commands" +--- + +# Cookieplone `make` commands + +This guide explains all the `make` commands found in a cookieplone project. + +## Frontend + +The Makefile at the root of your project invokes commands in frontend/Makefile. Here are excerpts from frontend/Makefile to show details of the frontend make commands. + +`frontend-install` + +The command `make frontend-install`: + +- Invokes the target `make install` in `frontend/Makefile`. + - This installs the add-ons in the development environment. + +`frontend-build` + +The command `make frontend-build`: + +- Invokes the target `make build` in `frontend/Makefile`. + - This creates a production bundle for distribution of the project with the add-on. + +`frontend-start` + +The command `make frontend-start`: + +- Invokes the target `make start` in `frontend/Makefile`. + - This starts Volto, allowing reloading of the add-on during development. + +`frontend-test` + +The command `make frontend-test`: + +- Invokes the target `make test` in `frontend/Makefile`. + - This runs unit tests. + + +## Backend + +The Makefile at the root of your project invokes commands in backend/Makefile. Here are excerpts from backend/Makefile to show details of the backend make commands. + +`backend-install` + +The command `make backend-install`: + +- Invokes the target `make install` in `backend/Makefile`. + - This creates a `Python` virtual environment if one does not exist. + - It then installs Plone and its dependencies in that virtual environment. + - After installation, it runs `make backend-create-site` to initialize a new Plone site. + +`backend-build` + +The command `make backend-build`: + +- Invokes the target `make install` in `backend/Makefile`. + - This creates a production bundle for distribution of the project with the add-on. + +`backend-create-site` + +The command `make backend-create-site`: + +- Invokes the target `make create-site` in `backend/Makefile`. + - This first ensures the virtual env exists. + - Creates a new Plone site with default content. + +`backend-update-example-content` + +The command `make backend-update-example-content`: + +- Invokes the target `make update-example-content` in `backend/Makefile`. + - This first ensures the virtual env exists. + - Checks if example-content exists. If yes, deletes all files inside to ensure a fresh export. + - Then exports the Plone content. + +`backend-start` + +The command `make backend-start`: + +- Invokes the target `make start` in `backend/Makefile`. + - This starts a Plone instance on localhost:8080. + +`backend-test` + +The command `make backend-test`: + +- Invokes the target `make test` in `backend/Makefile`. + - This runs unit tests. \ No newline at end of file diff --git a/docs/reference-guide/index.md b/docs/reference-guide/index.md index 2c93cbc8a..9eb400bac 100644 --- a/docs/reference-guide/index.md +++ b/docs/reference-guide/index.md @@ -12,6 +12,9 @@ myst: This reference guide details application programming interfaces (APIs), functions, modules, and objects included in Plone, describing what they are and what they do. Its audience is primarily developers of Plone and its projects and add-ons. +{doc}`Cookieplone make commands ` +: This lists all the `make` commands in a cookieplone project. + {doc}`Volto configuration settings ` : This reference contains a summary of the configuration options and what they control. @@ -30,6 +33,7 @@ Its audience is primarily developers of Plone and its projects and add-ons. ```{toctree} :hidden: +cookieplone-make-commands volto-configuration-settings volto-javascript-client plone.restapi-usage From a76576fb505cfca70672a82eeb6167f88c0fc574 Mon Sep 17 00:00:00 2001 From: Manas Kenge <110519001+Manas-Kenge@users.noreply.github.com> Date: Mon, 14 Apr 2025 10:09:39 +0530 Subject: [PATCH 2/4] fix format, add more commands --- .../cookieplone-make-commands.md | 156 ++++++++++++------ docs/reference-guide/index.md | 4 +- 2 files changed, 109 insertions(+), 51 deletions(-) diff --git a/docs/reference-guide/cookieplone-make-commands.md b/docs/reference-guide/cookieplone-make-commands.md index 818eec973..ce552ef71 100644 --- a/docs/reference-guide/cookieplone-make-commands.md +++ b/docs/reference-guide/cookieplone-make-commands.md @@ -9,88 +9,146 @@ myst: # Cookieplone `make` commands -This guide explains all the `make` commands found in a cookieplone project. +This reference guide describes the function and purpose of all the `make` commands found in a {term}`Cookieplone` project. +It's organized according to its components. +- Frontend +- Backend +- Documentation +- Environment +- Quality assurance (QA) +- Internationalization (i18n) +- Testing +- Container images +- Local stack +- Acceptance ## Frontend -The Makefile at the root of your project invokes commands in frontend/Makefile. Here are excerpts from frontend/Makefile to show details of the frontend make commands. +When you issue a `make` command at the root of your project, you call the file {file}`Makefile` also at the root. +In turn, it invokes commands in the file {file}`frontend/Makefile`. +You can refer to these files for implementation details. +You can run the following make targets by using the command structure of `make `. `frontend-install` +: Invokes the target `make install` in `frontend/Makefile`. + This installs the add-ons in the development environment. -The command `make frontend-install`: +`frontend-build` +: Invokes the target `make build` in `frontend/Makefile`. + This creates a production bundle for distribution of the project with the add-on. -- Invokes the target `make install` in `frontend/Makefile`. - - This installs the add-ons in the development environment. +`frontend-start` +: Invokes the target `make start` in `frontend/Makefile`. + This starts Volto, allowing reloading of the add-on during development. -`frontend-build` +`frontend-test` +: Invokes the target `make test` in `frontend/Makefile`. + This runs unit tests. -The command `make frontend-build`: -- Invokes the target `make build` in `frontend/Makefile`. - - This creates a production bundle for distribution of the project with the add-on. +## Backend -`frontend-start` +When you issue a `make` command at the root of your project, you call the file {file}`Makefile` also at the root. +In turn, it invokes commands in the file {file}`backend/Makefile`. +You can refer to these files for implementation details. +You can run the following make targets by using the command structure of `make `. -The command `make frontend-start`: +`backend-install` +: Invokes the target `make install` in `backend/Makefile`. + This creates a `Python` virtual environment if one does not exist. + It then installs Plone and its dependencies in that virtual environment. + After installation, it runs `make backend-create-site` to initialize a new Plone site. -- Invokes the target `make start` in `frontend/Makefile`. - - This starts Volto, allowing reloading of the add-on during development. +`backend-build` +: Invokes the target `make install` in `backend/Makefile`. + This creates a production bundle for distribution of the project with the add-on. -`frontend-test` +`backend-create-site` +: Invokes the target `make create-site` in `backend/Makefile`. + This first ensures the virtual env exists. + Creates a new Plone site with default content. + +`backend-update-example-content` +: Invokes the target `make update-example-content` in `backend/Makefile`. + This first ensures the virtual env exists. + Checks if example-content exists. If yes, deletes all files inside to ensure a fresh export. + Then exports the Plone content. -The command `make frontend-test`: +`backend-start` +: Invokes the target `make start` in `backend/Makefile`. + This starts a Plone instance on localhost:8080. -- Invokes the target `make test` in `frontend/Makefile`. - - This runs unit tests. +`backend-test` +: Invokes the target `make test` in `backend/Makefile`. + This runs unit tests. -## Backend +## Environment -The Makefile at the root of your project invokes commands in backend/Makefile. Here are excerpts from backend/Makefile to show details of the backend make commands. +When you issue a `make` command at the root of your project, you call the file {file}`Makefile` also at the root. +In turn, it invokes commands in the files {file}`backend/Makefile` and {file}`frontend/Makefile`. +You can refer to these files for implementation details. +You can run the following make targets by using the command structure of `make `. -`backend-install` +`install` +: Invokes the target `make backend-install` and `make frontend-install` in `backend/Makefile` and `frontend/Makefile` respectively. + This installs the add-ons in the development environment for both backend and frontend. -The command `make backend-install`: +`clean` +: Invokes the target `make clean` in both `backend/Makefile` and `frontend/Makefile`. + This command cleans both backend (removing virtual environments, cached files, and instance data) and frontend (removing core files and node_modules) environments. -- Invokes the target `make install` in `backend/Makefile`. - - This creates a `Python` virtual environment if one does not exist. - - It then installs Plone and its dependencies in that virtual environment. - - After installation, it runs `make backend-create-site` to initialize a new Plone site. -`backend-build` +## Quality assurance (QA) -The command `make backend-build`: +When you issue a `make` command at the root of your project, you call the file {file}`Makefile` also at the root. +In turn, it invokes commands in the files {file}`backend/Makefile` and {file}`frontend/Makefile`. +You can refer to these files for implementation details. +You can run the following make targets by using the command structure of `make `. -- Invokes the target `make install` in `backend/Makefile`. - - This creates a production bundle for distribution of the project with the add-on. +`format` +: Invokes the target `make format` in both `backend/Makefile` and `frontend/Makefile`. + This formats the codebase according to Plone standards -`backend-create-site` +`lint` +: Invokes the target `make lint` in both `backend/Makefile` and `frontend/Makefile`. + Checks for problems (linting, formatting, style issues) but does not auto-fix them, it only reports errors. -The command `make backend-create-site`: +`check` +: Runs both `format` and `lint` in sequence. -- Invokes the target `make create-site` in `backend/Makefile`. - - This first ensures the virtual env exists. - - Creates a new Plone site with default content. - -`backend-update-example-content` -The command `make backend-update-example-content`: +## Internationalization (i18n) -- Invokes the target `make update-example-content` in `backend/Makefile`. - - This first ensures the virtual env exists. - - Checks if example-content exists. If yes, deletes all files inside to ensure a fresh export. - - Then exports the Plone content. +When you issue a `make` command at the root of your project, you call the file {file}`Makefile` also at the root. +In turn, it invokes commands in the files {file}`backend/Makefile` and {file}`frontend/Makefile`. +You can refer to these files for implementation details. +You can run the following make targets by using the command structure of `make `. -`backend-start` +`i18n` +: Invokes the target `make i18n` in both `backend/Makefile` and `frontend/Makefile`. + It is used to update locales in your project. -The command `make backend-start`: -- Invokes the target `make start` in `backend/Makefile`. - - This starts a Plone instance on localhost:8080. +## Testing -`backend-test` +When you issue a `make` command at the root of your project, you call the file {file}`Makefile` also at the root. +In turn, it invokes commands in the files {file}`backend/Makefile` and {file}`frontend/Makefile`. +You can refer to these files for implementation details. +You can run the following make targets by using the command structure of `make `. + +`test` +: Invokes the target `make backend-test` and `make frontend-test` in `backend/Makefile` and `frontend/Makefile` respectively. + This runs unit tests in the project. + + +## Container images -The command `make backend-test`: +When you issue a `make` command at the root of your project, you call the file {file}`Makefile` also at the root. +In turn, it invokes commands in the files {file}`backend/Makefile` and {file}`frontend/Makefile`. +You can refer to these files for implementation details. +You can run the following make targets by using the command structure of `make `. -- Invokes the target `make test` in `backend/Makefile`. - - This runs unit tests. \ No newline at end of file +`build-images` +: Invokes the target `make build-image` in both `backend/Makefile` and `frontend/Makefile`. + This build Docker Images for both backend and frontend. \ No newline at end of file diff --git a/docs/reference-guide/index.md b/docs/reference-guide/index.md index 9eb400bac..f7724d32b 100644 --- a/docs/reference-guide/index.md +++ b/docs/reference-guide/index.md @@ -12,8 +12,8 @@ myst: This reference guide details application programming interfaces (APIs), functions, modules, and objects included in Plone, describing what they are and what they do. Its audience is primarily developers of Plone and its projects and add-ons. -{doc}`Cookieplone make commands ` -: This lists all the `make` commands in a cookieplone project. +{doc}`/reference-guide/cookieplone-make-commands` +: This chapter describes all the `make` commands in a {term}`Cookieplone` project. {doc}`Volto configuration settings ` : This reference contains a summary of the configuration options and what they control. From 808696811c13d49adbe40e6eb17ef29e493a8827 Mon Sep 17 00:00:00 2001 From: Manas Kenge <110519001+Manas-Kenge@users.noreply.github.com> Date: Tue, 15 Apr 2025 00:59:34 +0530 Subject: [PATCH 3/4] format grammar --- .../cookieplone-make-commands.md | 59 ++++++++++--------- 1 file changed, 31 insertions(+), 28 deletions(-) diff --git a/docs/reference-guide/cookieplone-make-commands.md b/docs/reference-guide/cookieplone-make-commands.md index ce552ef71..c12fb8a83 100644 --- a/docs/reference-guide/cookieplone-make-commands.md +++ b/docs/reference-guide/cookieplone-make-commands.md @@ -30,19 +30,21 @@ You can refer to these files for implementation details. You can run the following make targets by using the command structure of `make `. `frontend-install` -: Invokes the target `make install` in `frontend/Makefile`. - This installs the add-ons in the development environment. +: Invokes the target `install` in `frontend/Makefile`. + Uses pnpm to run the mrs-developer tool with the default settings. + It then installs dependencies using pnpm. + After that, it runs `build-deps` to build dependency packages. `frontend-build` -: Invokes the target `make build` in `frontend/Makefile`. +: Invokes the target `build` in `frontend/Makefile`. This creates a production bundle for distribution of the project with the add-on. `frontend-start` -: Invokes the target `make start` in `frontend/Makefile`. +: Invokes the target `start` in `frontend/Makefile`. This starts Volto, allowing reloading of the add-on during development. `frontend-test` -: Invokes the target `make test` in `frontend/Makefile`. +: Invokes the target `test` in `frontend/Makefile`. This runs unit tests. @@ -54,32 +56,32 @@ You can refer to these files for implementation details. You can run the following make targets by using the command structure of `make `. `backend-install` -: Invokes the target `make install` in `backend/Makefile`. +: Invokes the target `install` in `backend/Makefile`. This creates a `Python` virtual environment if one does not exist. It then installs Plone and its dependencies in that virtual environment. - After installation, it runs `make backend-create-site` to initialize a new Plone site. + After installation, it runs `make backend-create-site` to initialize a new Plone site with default content. `backend-build` -: Invokes the target `make install` in `backend/Makefile`. +: Invokes the target `install` in `backend/Makefile`. This creates a production bundle for distribution of the project with the add-on. `backend-create-site` -: Invokes the target `make create-site` in `backend/Makefile`. - This first ensures the virtual env exists. +: Invokes the target `create-site` in `backend/Makefile`. + This first ensures the virtual environment exists. Creates a new Plone site with default content. `backend-update-example-content` -: Invokes the target `make update-example-content` in `backend/Makefile`. - This first ensures the virtual env exists. - Checks if example-content exists. If yes, deletes all files inside to ensure a fresh export. - Then exports the Plone content. +: Invokes the target `update-example-content` in `backend/Makefile`. + This first ensures the virtual environment exists. + Next, it removes all content from the destination directory, if any content exists. + Finally, it exports the Plone site content. `backend-start` -: Invokes the target `make start` in `backend/Makefile`. - This starts a Plone instance on localhost:8080. +: Invokes the target `start` in `backend/Makefile`. + This starts a Plone instance on `localhost:8080`. `backend-test` -: Invokes the target `make test` in `backend/Makefile`. +: Invokes the target `test` in `backend/Makefile`. This runs unit tests. @@ -91,11 +93,11 @@ You can refer to these files for implementation details. You can run the following make targets by using the command structure of `make `. `install` -: Invokes the target `make backend-install` and `make frontend-install` in `backend/Makefile` and `frontend/Makefile` respectively. +: Invokes the target `backend-install` and `make frontend-install` in `backend/Makefile` and `frontend/Makefile` respectively. This installs the add-ons in the development environment for both backend and frontend. `clean` -: Invokes the target `make clean` in both `backend/Makefile` and `frontend/Makefile`. +: Invokes the target `clean` in both `backend/Makefile` and `frontend/Makefile`. This command cleans both backend (removing virtual environments, cached files, and instance data) and frontend (removing core files and node_modules) environments. @@ -107,12 +109,13 @@ You can refer to these files for implementation details. You can run the following make targets by using the command structure of `make `. `format` -: Invokes the target `make format` in both `backend/Makefile` and `frontend/Makefile`. - This formats the codebase according to Plone standards +: Invokes the target `format` in both `backend/Makefile` and `frontend/Makefile`. + This formats the code base according to Plone standards `lint` -: Invokes the target `make lint` in both `backend/Makefile` and `frontend/Makefile`. - Checks for problems (linting, formatting, style issues) but does not auto-fix them, it only reports errors. +: Invokes the target `lint` in both `backend/Makefile` and `frontend/Makefile`. + Checks for problems—such as linting, formatting, and style issues—but does not auto-fix them. + It only reports errors. `check` : Runs both `format` and `lint` in sequence. @@ -126,8 +129,8 @@ You can refer to these files for implementation details. You can run the following make targets by using the command structure of `make `. `i18n` -: Invokes the target `make i18n` in both `backend/Makefile` and `frontend/Makefile`. - It is used to update locales in your project. +: Invokes the target `i18n` in both `backend/Makefile` and `frontend/Makefile`. + It updates translations in your project. ## Testing @@ -138,7 +141,7 @@ You can refer to these files for implementation details. You can run the following make targets by using the command structure of `make `. `test` -: Invokes the target `make backend-test` and `make frontend-test` in `backend/Makefile` and `frontend/Makefile` respectively. +: Invokes the target `backend-test` and `make frontend-test` in `backend/Makefile` and `frontend/Makefile` respectively. This runs unit tests in the project. @@ -150,5 +153,5 @@ You can refer to these files for implementation details. You can run the following make targets by using the command structure of `make `. `build-images` -: Invokes the target `make build-image` in both `backend/Makefile` and `frontend/Makefile`. - This build Docker Images for both backend and frontend. \ No newline at end of file +: Invokes the target `build-image` in both `backend/Makefile` and `frontend/Makefile`. + This builds Docker images for both backend and frontend. \ No newline at end of file From d97eb45853ba2b221d9f30b1ed07e6878a577433 Mon Sep 17 00:00:00 2001 From: Manas Kenge Date: Tue, 15 Apr 2025 22:08:53 +0530 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Steve Piercy --- docs/reference-guide/cookieplone-make-commands.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/reference-guide/cookieplone-make-commands.md b/docs/reference-guide/cookieplone-make-commands.md index c12fb8a83..3b1ebdd6f 100644 --- a/docs/reference-guide/cookieplone-make-commands.md +++ b/docs/reference-guide/cookieplone-make-commands.md @@ -31,9 +31,9 @@ You can run the following make targets by using the command structure of `make < `frontend-install` : Invokes the target `install` in `frontend/Makefile`. - Uses pnpm to run the mrs-developer tool with the default settings. - It then installs dependencies using pnpm. - After that, it runs `build-deps` to build dependency packages. + Uses `pnpm dlx` to run [mrs-developer](https://github.com/collective/mrs-developer) to retrieve dependencies in the file {file}`frontend/mrs.developer.json`. + It then installs the dependencies. + Finally, it builds the dependency packages `@plone/registry` and `@plone/components` from source. `frontend-build` : Invokes the target `build` in `frontend/Makefile`. @@ -63,7 +63,9 @@ You can run the following make targets by using the command structure of `make < `backend-build` : Invokes the target `install` in `backend/Makefile`. - This creates a production bundle for distribution of the project with the add-on. + This creates a `Python` virtual environment if one does not exist. + It then installs Plone and its dependencies in that virtual environment. + This is useful when you need to reload changes from your backend add-on, and don't need to recreate a full Plone site. `backend-create-site` : Invokes the target `create-site` in `backend/Makefile`. @@ -110,7 +112,7 @@ You can run the following make targets by using the command structure of `make < `format` : Invokes the target `format` in both `backend/Makefile` and `frontend/Makefile`. - This formats the code base according to Plone standards + This formats the code base according to Plone standards. `lint` : Invokes the target `lint` in both `backend/Makefile` and `frontend/Makefile`.