Skip to content

Commit 451ef78

Browse files
Manas-Kengestevepiercy
Manas-Kenge
and
stevepiercy
authored
Reference Guide for Cookieplone make commands (#1934)
* add FE & BE commands * fix format, add more commands * format grammar * Apply suggestions from code review Co-authored-by: Steve Piercy <[email protected]> --------- Co-authored-by: Steve Piercy <[email protected]>
1 parent 561ef75 commit 451ef78

File tree

2 files changed

+163
-0
lines changed

2 files changed

+163
-0
lines changed

‎docs/reference-guide/cookieplone-make-commands.md

+159
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
---
2+
myst:
3+
html_meta:
4+
"description": "Cookieplone make commands"
5+
"property=og:description": "Cookieplone make commands"
6+
"property=og:title": "Cookieplone make commands"
7+
"keywords": "Cookieplone, make, commands"
8+
---
9+
10+
# Cookieplone `make` commands
11+
12+
This reference guide describes the function and purpose of all the `make` commands found in a {term}`Cookieplone` project.
13+
It's organized according to its components.
14+
- Frontend
15+
- Backend
16+
- Documentation
17+
- Environment
18+
- Quality assurance (QA)
19+
- Internationalization (i18n)
20+
- Testing
21+
- Container images
22+
- Local stack
23+
- Acceptance
24+
25+
## Frontend
26+
27+
When you issue a `make` command at the root of your project, you call the file {file}`Makefile` also at the root.
28+
In turn, it invokes commands in the file {file}`frontend/Makefile`.
29+
You can refer to these files for implementation details.
30+
You can run the following make targets by using the command structure of `make <TARGET>`.
31+
32+
`frontend-install`
33+
: Invokes the target `install` in `frontend/Makefile`.
34+
Uses `pnpm dlx` to run [mrs-developer](https://github.com/collective/mrs-developer) to retrieve dependencies in the file {file}`frontend/mrs.developer.json`.
35+
It then installs the dependencies.
36+
Finally, it builds the dependency packages `@plone/registry` and `@plone/components` from source.
37+
38+
`frontend-build`
39+
: Invokes the target `build` in `frontend/Makefile`.
40+
This creates a production bundle for distribution of the project with the add-on.
41+
42+
`frontend-start`
43+
: Invokes the target `start` in `frontend/Makefile`.
44+
This starts Volto, allowing reloading of the add-on during development.
45+
46+
`frontend-test`
47+
: Invokes the target `test` in `frontend/Makefile`.
48+
This runs unit tests.
49+
50+
51+
## Backend
52+
53+
When you issue a `make` command at the root of your project, you call the file {file}`Makefile` also at the root.
54+
In turn, it invokes commands in the file {file}`backend/Makefile`.
55+
You can refer to these files for implementation details.
56+
You can run the following make targets by using the command structure of `make <TARGET>`.
57+
58+
`backend-install`
59+
: Invokes the target `install` in `backend/Makefile`.
60+
This creates a `Python` virtual environment if one does not exist.
61+
It then installs Plone and its dependencies in that virtual environment.
62+
After installation, it runs `make backend-create-site` to initialize a new Plone site with default content.
63+
64+
`backend-build`
65+
: Invokes the target `install` in `backend/Makefile`.
66+
This creates a `Python` virtual environment if one does not exist.
67+
It then installs Plone and its dependencies in that virtual environment.
68+
This is useful when you need to reload changes from your backend add-on, and don't need to recreate a full Plone site.
69+
70+
`backend-create-site`
71+
: Invokes the target `create-site` in `backend/Makefile`.
72+
This first ensures the virtual environment exists.
73+
Creates a new Plone site with default content.
74+
75+
`backend-update-example-content`
76+
: Invokes the target `update-example-content` in `backend/Makefile`.
77+
This first ensures the virtual environment exists.
78+
Next, it removes all content from the destination directory, if any content exists.
79+
Finally, it exports the Plone site content.
80+
81+
`backend-start`
82+
: Invokes the target `start` in `backend/Makefile`.
83+
This starts a Plone instance on `localhost:8080`.
84+
85+
`backend-test`
86+
: Invokes the target `test` in `backend/Makefile`.
87+
This runs unit tests.
88+
89+
90+
## Environment
91+
92+
When you issue a `make` command at the root of your project, you call the file {file}`Makefile` also at the root.
93+
In turn, it invokes commands in the files {file}`backend/Makefile` and {file}`frontend/Makefile`.
94+
You can refer to these files for implementation details.
95+
You can run the following make targets by using the command structure of `make <TARGET>`.
96+
97+
`install`
98+
: Invokes the target `backend-install` and `make frontend-install` in `backend/Makefile` and `frontend/Makefile` respectively.
99+
This installs the add-ons in the development environment for both backend and frontend.
100+
101+
`clean`
102+
: Invokes the target `clean` in both `backend/Makefile` and `frontend/Makefile`.
103+
This command cleans both backend (removing virtual environments, cached files, and instance data) and frontend (removing core files and node_modules) environments.
104+
105+
106+
## Quality assurance (QA)
107+
108+
When you issue a `make` command at the root of your project, you call the file {file}`Makefile` also at the root.
109+
In turn, it invokes commands in the files {file}`backend/Makefile` and {file}`frontend/Makefile`.
110+
You can refer to these files for implementation details.
111+
You can run the following make targets by using the command structure of `make <TARGET>`.
112+
113+
`format`
114+
: Invokes the target `format` in both `backend/Makefile` and `frontend/Makefile`.
115+
This formats the code base according to Plone standards.
116+
117+
`lint`
118+
: Invokes the target `lint` in both `backend/Makefile` and `frontend/Makefile`.
119+
Checks for problems—such as linting, formatting, and style issues—but does not auto-fix them.
120+
It only reports errors.
121+
122+
`check`
123+
: Runs both `format` and `lint` in sequence.
124+
125+
126+
## Internationalization (i18n)
127+
128+
When you issue a `make` command at the root of your project, you call the file {file}`Makefile` also at the root.
129+
In turn, it invokes commands in the files {file}`backend/Makefile` and {file}`frontend/Makefile`.
130+
You can refer to these files for implementation details.
131+
You can run the following make targets by using the command structure of `make <TARGET>`.
132+
133+
`i18n`
134+
: Invokes the target `i18n` in both `backend/Makefile` and `frontend/Makefile`.
135+
It updates translations in your project.
136+
137+
138+
## Testing
139+
140+
When you issue a `make` command at the root of your project, you call the file {file}`Makefile` also at the root.
141+
In turn, it invokes commands in the files {file}`backend/Makefile` and {file}`frontend/Makefile`.
142+
You can refer to these files for implementation details.
143+
You can run the following make targets by using the command structure of `make <TARGET>`.
144+
145+
`test`
146+
: Invokes the target `backend-test` and `make frontend-test` in `backend/Makefile` and `frontend/Makefile` respectively.
147+
This runs unit tests in the project.
148+
149+
150+
## Container images
151+
152+
When you issue a `make` command at the root of your project, you call the file {file}`Makefile` also at the root.
153+
In turn, it invokes commands in the files {file}`backend/Makefile` and {file}`frontend/Makefile`.
154+
You can refer to these files for implementation details.
155+
You can run the following make targets by using the command structure of `make <TARGET>`.
156+
157+
`build-images`
158+
: Invokes the target `build-image` in both `backend/Makefile` and `frontend/Makefile`.
159+
This builds Docker images for both backend and frontend.

‎docs/reference-guide/index.md

+4
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,9 @@ myst:
1212
This reference guide details application programming interfaces (APIs), functions, modules, and objects included in Plone, describing what they are and what they do.
1313
Its audience is primarily developers of Plone and its projects and add-ons.
1414

15+
{doc}`/reference-guide/cookieplone-make-commands`
16+
: This chapter describes all the `make` commands in a {term}`Cookieplone` project.
17+
1518
{doc}`Volto configuration settings </volto/configuration/settings-reference>`
1619
: This reference contains a summary of the configuration options and what they control.
1720

@@ -30,6 +33,7 @@ Its audience is primarily developers of Plone and its projects and add-ons.
3033

3134
```{toctree}
3235
:hidden:
36+
cookieplone-make-commands
3337
volto-configuration-settings
3438
volto-javascript-client
3539
plone.restapi-usage

0 commit comments

Comments
 (0)