Fix duplicate docs generation into backend

[ujsquared]

Fixes #202

I think I missed these two lines while restructuring. Already present in frontend_addon

[ujsquared]

Something remaining to be discussed here is what to do with the templates/add-ons/backend/docs directory generation itself (It was already present in the template and had a .gitkeep file in it). Is there any point to it now?

[stevepiercy]

LGTM. Let's see if we can get an answer regarding your question before merging. Thank you!

[stevepiercy]

Something remaining to be discussed here is what to do with the templates/add-ons/backend/docs directory generation itself (It was already present in the template and had a .gitkeep file in it). Is there any point to it now?

I did a little digging around. It was part of the initial commit, but without comment for its existence.

https://github.com/plone/cookieplone-templates/commits/0cbac78bbfd68ecc11174c502af50e8ccf70910f/backend_addon/%7B%7B%20cookiecutter.__folder_name%20%7D%7D/docs/.gitkeep

I assume that Érico had a plan for it at the time, and using .gitkeep served as a placeholder and reminder to eventually provide docs for a backend add-on. I distinctly remember his request to me for a documentation Cookieplone template at Axolotl Sprint 2024. However, we have since realized that a project could have both a frontend and backend add-on to function in Plone, or neither, so having docs as a sibling to both frontend and backend makes sense. Maybe @davisagli, @ericof, or @sneridagh can recall. If not, I'll make the call to remove templates/add-ons/backend/docs/*.

[davisagli]

I would remove the empty docs folder in the backend scaffold. The new documentation starter scaffold takes its place.

[stevepiercy]

Tested. Success!

[stevepiercy]

@davisagli @ericof should we change the CI to allow it to run from forks? There are two jobs that are waiting for a status to be reported. Here's what we did in Volto:

https://github.com/plone/volto/blob/main/.github/workflows/acceptance.yml#L2-L5

But I don't know how to merge it with our main workflow:

https://github.com/plone/cookieplone-templates/blob/main/.github/workflows/main.yml#L4-L6

Also can we merge this PR?

[davisagli]

Wouldn't it be a bit more straightforward to make the project template explicitly set initialize_documentation to false in the context that it uses when it calls the backend_addon template as a subtemplate? https://github.com/plone/cookieplone-templates/blob/main/templates/projects/monorepo/hooks/post_gen_project.py#L64

[davisagli]

should we change the CI to allow it to run from forks? There are two jobs that are waiting for a status to be reported. Here's what we did in Volto / But I don't know how to merge it with our main workflow:

@stevepiercy I don't like the solution we used for Volto because it always shows lots of skipped checks. What we've done elsewhere is set the workflow to trigger on a push event for the main branch or a pull_request event that targets the main branch.

[stevepiercy]

Wouldn't it be a bit more straightforward to make the project template explicitly set initialize_documentation to false in the context that it uses when it calls the backend_addon template as a subtemplate? https://github.com/plone/cookieplone-templates/blob/main/templates/projects/monorepo/hooks/post_gen_project.py#L64

I had to look up the term "context" in Cookiecutter docs, but its definition doesn't exist. This is the file I tried to examine: https://cookiecutter.readthedocs.io/en/stable/cookiecutter.html. It appears there is a context dict, a context template, and a context project.

Anyway, @davisagli, is your suggestion the same as mine in the original issue, IOW, prevent creating the backend/docs directory in the first place?

[stevepiercy]

What we've done elsewhere is set the workflow to trigger on a push event for the main branch or a pull_request event that targets the main branch.

@davisagli got link to example? I can try to replicate its usage for cookieplone-templates in a separate PR.

[ujsquared]

Wouldn't it be a bit more straightforward to make the project template explicitly set initialize_documentation to false in the context that it uses when it calls the backend_addon template as a subtemplate? https://github.com/plone/cookieplone-templates/blob/main/templates/projects/monorepo/hooks/post_gen_project.py#L64

I'm assuming that would mean adding the generate documentation scaffold part to the list of other actions. If I remember correctly, I tried that and could not find a reliable way to set the context value to False once QUIET_MODE_VAR is 1. Will report after trying it again.

[ujsquared]

Update: I have tried a new approach, which follows @davisagli advice. Also some formatting fixes.

[stevepiercy]

Minor tweaks for consistency

[stevepiercy]

Checked out, generated project, ran make test from repo root, and it's all good for me, except for that one test that fails on my system, but not @ujsquared's. You can try to reproduce it with the following command.

uv run pytest tests/templates/add-ons/documentation_starter/test_cutter.py

[stevepiercy]

LGTM. Let's get @davisagli to review the changes.

[davisagli]

What we've done elsewhere is set the workflow to trigger on a push event for the main branch or a pull_request event that targets the main branch.

@davisagli got link to example? I can try to replicate its usage for cookieplone-templates in a separate PR.

@stevepiercy done in #212

[stevepiercy]

@davisagli could I get a review from you on @ujsquared's changes per your feedback to him? Thank you!

[davisagli]

@stevepiercy Yes, I will. Had to take a break to make dinner

[davisagli]

This is making it a bit more complicated than it needs to be. It was easier to show what I wanted to do differently rather than explain how to do it, so I made a new PR: #218

[ujsquared]

Let's get this closed and merge #218 instead.

[stevepiercy]

Closing in favor of #218