Create a Reference Guide with Cookieplone make commands and prompt reference

[stevepiercy]

Links of affected pages in Plone Documentation, if any.

No response

Description

After generating a full Plone project with Cookieplone, you can run make help to get an almost complete list of make commands with help text. Enhance that output by organizing them or adding context, such as Frontend and Backend. The help text output from the make help command is often not sufficient for first-timers.

• Create a new page in the yet to be created Reference Guide, "Cookieplone make reference", at docs/reference/cookieplone-make-commands.md.
• Create docs/reference/index.md and reference the previous file.
• Add an entry to the toctree in docs/index.md referencing the previous file.
• Write a detailed explanation of what each of the prompts does, where it is not clear from the README.md or the help text.

[GOGETASSB23]

Hello @stevepiercy sir,

I'd like to work on this issue and contribute to the Plone documentation. I have already set up the documentation environment and started exploring the make help command.

Could you please assign this issue to me? Also , in order to get the list of make commands can i generate the project using 2nd training(volto-customization using javascript)

Looking forward to your guidance. Thanks!

regards,
Aryan

[stevepiercy]

@GOGETASSB23 thank you for your interest!

We don't assign issues. You can claim them. See Things not to do.

See also Install Plone with Cookieplone, which is the authoritative source for doing just that.

[GOGETASSB23]

@stevepiercy sir, taking into consideration the guidelines to follow the Set up,build and check the quality of documentation, I created a new fork and started over.

I have a doubt regarding the setup. When using mkdocs serve, we add the file to the nav section of mkdocs.yml to reflect changes in the documentation. However, the documentation asks us to use the make livehtml command (Sphinx-autobuild server).

So, according to the suggested documentation, I need to follow make livehtml to run the server. Where do I add the file (cookieplone-make-commands.md) so that it reflects changes on my local server?

this doubt has been solved, thank you..

[stevepiercy]

We don't use mkdocs. We use Sphinx.

make livehtml only watches files that exist at the moment it is launched. You must first create the file, then make livehtml can watch it for changes.

The new file should go in a new directory:

docs/reference/cookieplone-make-commands.md

New files also require a toctree entry, else they do not appear in the sidebar navigation. We will need to add another new file:

docs/reference/index.md

...which will contain the toctree that references the new documentation.

Finally, the primary docs/index.md will need reference/index added to its toctree.

[Manas-Kenge]

@stevepiercy How much detailed explanation is required here? Also, there are three Makefiles — one each for the root, frontend, and backend. Should the documentation cover all of them? If so, I assume three separate sections will be needed.

[stevepiercy]

@Manas-Kenge thanks for your interest.

It's not obvious, but most make commands can be run from the root of the project. There may be exceptions, such as documentation_starter in a PR that is nearing completion. That fact needs to be documented, too.

If you look at the root Makefile, note the following.

###########################################
# Frontend
###########################################
.PHONY: frontend-install
frontend-install:  ## Install React Frontend
	$(MAKE) -C "./frontend/" install

Here you can see that make frontend-install will call the make command make install in frontend/Makefile. This in turn will call the following make target.

.PHONY: install
install: ## Installs the add-on in a development environment
	pnpm dlx mrs-developer missdev --no-config --fetch-https
	pnpm i
	make build-deps

The level of detail is subjective. We don't want "word salad" or know "how sausage is made", yet the existing terse Install React Frontend is not very helpful unless you already know the concepts of Plone having a backend and frontend, one of which uses React. You can follow my process.

1. Turn off my brain. Pretend I have only a basic knowledge of Plone, Python, and React, and write according to that level.
2. Create a Cookieplone project.
3. When I stumble on a term or phrase, be resourceful.
   1. Refer to each of the README.md files.
   2. Refer to each of the Makefile files.
   3. Run make help at the root and in each subfolder.
   4. Refer to Plone 6 Documentation.
4. Write descriptions that provide sufficient detail of the make command for my turned off brain.
5. Refer to existing documentation when needed.
6. Create or refer to existing terms in the Glossary.

Finally, I'd organize it following the root Makefile's organization. I would enhance each of these sections with commands that are not supported at the root but only in the sub-folder. Due to the large number of commands, I'd also only do one or two commands for each section at first, create a PR, and ask if I'm heading in the right direction.

Does that help?

[acsr]

The canonical startpoint link to this detailed cookieplone make commands docs (when initially available to docs) should be mentioned in the final console output of a cookieplone run and the main README.md.

Question: Does it make sense to open up a ticket there until this one is finished.

I enjoyed the extended explanation @sneridagh used in the final console output of his seventemplate branch/tag. This is the first place to avoid confusion for newbies.

[stevepiercy]

@acsr please see screenshot, and create a new issue in both Cookieplone and cookieplone-templates repos, referencing this issue.

[Manas-Kenge]

Thanks for the clarification @stevepiercy! I will do my best.

[acsr]

@acsr please see screenshot, and create a new issue in both Cookieplone and cookieplone-templates repos, referencing this issue.

Done, see referenced tickets by github above.

@stevepiercy should be also become part of the docs for the creation of cookieplone templates make sure new templates contain a proper motivating and clarifying final console message to point to the startpoints in the Readme and the docs.

[stevepiercy]

@stevepiercy should be also become part of the docs for the creation of cookieplone templates make sure new templates contain a proper motivating and clarifying final console message to point to the startpoints in the Readme and the docs.

@acsr if you're talking about how to contribute to cookieplone-templates, that's already done in https://github.com/plone/cookieplone-templates?tab=readme-ov-file#contribute-, per a recent PR merge. Specific contributing guidelines don't belong in the main documentation—except for submodules that get pulled in automatically—as it is specific to just that project and would become a duplicitous maintenance burden.

Otherwise I don't know what you mean. Can you give an example?

[acsr]

Example moved to different location…

[stevepiercy]

@acsr I'm sorry, but you've gone far off topic for this issue, which is merely documenting make command usage. Please open a separate issue in the correct repo for these concerns.

[acsr]

@stevepiercy you asked for an example here, that was already mentioned. I moved the topic to these locations already and failed to get that we are here in the different context. I remove the above answer for keeping clarity.