Add documentation_starter to cookieplone-templates/templates

[ujsquared]

Fixes #7
Fixes plone/plone-sphinx-theme#3

Overview

This pull request introduces the documentation_addon template to the cookieplone-templates repository.
The template generates a Sphinx-based documentation environment for Plone projects, leveraging the latest plone-sphinx-theme from PyPI. It includes a comprehensive test suite to support both ongoing development and ensure reliable template generation.

Changes

There's loads of additions in this PR, so let's break it down:

Folder Structure

documentation_addon
├── {{cookiecutter.__folder_name}}
│   └── docs
│       ├── guides
│       ├── reference
│       └── _static
├── hooks
└── tests

• {{cookiecutter.__folder_name}}/: The core template directory that becomes the generated project (e.g., collective.example.docs).

  • docs/: Contains Sphinx documentation files.

    • docs/guides/: Templated directory helping user structure their documentation using getting-started.md, usage.md etc.

    • docs/reference/: Includes technical reference docs (file-system-structure.md, index.md, theme-elements.md).

    • _static/: Static assets (favicon.ico, logo.svg) for branding.

• hooks/: Contains post_gen_project.py for post-generation tasks (e.g., Git initialization). Can be used to add more hooks in the future for e.g. pre-generation hook.

• tests/: Test suite with conftest.py and test_template.py for template validation.

• Root Files: Essential project files (pyproject.toml, Makefile, README.md, etc.) for setup and building.

  • cookiecutter.json: Configuration file defining template variables and prompts.

  • Makefile: Top-level Makefile for mostly for running tests during development of documentation_addon.

Template Features

• Plone Docs like Environment: Generates a ready-to-use Sphinx setup with conf.py, pre-configured for plone-sphinx-theme.

• Dynamic Variables: Uses Jinja2 variables (e.g., {{ cookiecutter.title }}, {{ cookiecutter.__folder_name }}) for customization.

• Git Support: Optional Git initialization via __documentation_addon_git_initialize toggle in cookiecutter.json.

To-do/Improvements

• Check for buildout issue fix.
• Better Documentation of the {{cookiecutter.__folder_name}}.
• Integration with the A Plone project add-on option.
• Add Towncrier? [Needs Discussion]

PS: currently, the build of generated documentation fails, due to a issue with buildout 🙁.

[stevepiercy]

I am super excited by your work, @ujsquared! I have a lot on my plate at the moment, and hope to review this weekend. I've also requested reviews from people who I think would be interested in this add-on.

[ujsquared]

I am super excited by your work, @ujsquared! I have a lot on my plate at the moment, and hope to review this weekend. I've also requested reviews from people who I think would be interested in this add-on.

No worries!

[ksuess]

Is this an add-on?

[ksuess]

you may want to create a cookuiecutter template for a documentation project with Sphinx theme Plone-Sphinx-Theme

[stevepiercy]

@ksuess it's a cookieplone template that allows a person to generate docs for their project, without using sphinx-quickstart and already having PST and its extensions available.

[ksuess]

Oops, typo. Should read cookiecutter template

[ksuess]

Is this a Plone project or a Plone add-on?
If not, why should this be inxluded in a Plone rocket starter?

[ksuess]

https://github.com/cookiecutter/cookiecutter

[stevepiercy]

@ksuess I think you don't understand what this PR intends. It's not a Plone add-on. It's a Cookieplone template, similar to the backend and frontend. It generates a scaffold to create documentation for a Plone project generated from Cookieplone. Without it, a generated project does not have any documentation except for the default READMEs. Does that clarify?

[ksuess]

Let's see how cookieplone evolves.

[sneridagh]

I'm also excited about this one. I myself was in the need of this:

• Having an existing project, created with cookieplone, can I add easily now the boilerplate for the recommended documentation infrastructure?
• Or, I am creating my project/add-on and I'd like to add from the beginning the documentation infrastructure.

But, I have questions to the current shape too. So, @ksuess is correct, it's nor a Volto add-on, nor a classicUI add-on. So call it add-on might lead to confusion since there's no such thing as a "documentation add-on".

Does it address the two things above? @ericof would cookieplone/cookiecutter allow this? I can recall you telling me that this was a limitation.

[ujsquared]

• Having an existing project, created with cookieplone, can I add easily now the boilerplate for the recommended documentation infrastructure?

Absolutely. This feature was proposed keeping in mind the idea of letting users to effortlessly create some form of documentation (based on plone-sphinx-theme) alongside their new plone app/add-on. All of this, using prompts to guide them in filling out the boilerplate details, should save the efforts and time to write documentation.

• Or, I am creating my project/add-on and I'd like to add from the beginning the documentation infrastructure.

This feature hasn't been implemented. It's possible that we could add it by making changes here, but I'm not certain

But, I have questions to the current shape too. So, @ksuess is correct, it's nor a Volto add-on, nor a classicUI add-on. So call it add-on might lead to confusion since there's no such thing as a "documentation add-on".

To maintain consistency with the existing backend-addon and frontend-addon naming scheme in the code base, I named it documentation-addon. I think we can find better naming options.

[stevepiercy]

Regarding the use of "_addon" in this template's name, it's reusing the patterns of frontend_addon and backend_addon without really thinking it through. I think renaming it to documentation_scaffold or similar would make more sense. documentation alone is an ambiguous name. Let's choose a good name before refactoring.

[davisagli]

Thanks for getting this started @ujsquared. I haven't done a detailed review of the template yet; I want to give some comments on the overall structure first.

First, I agree with the other comments that using addon in the name is wrong, because the thing it creates is not a Plone add-on. I would be okay with documentation_template or documentation_project as an alternative. (Or, open to other suggestions)

Currently this is set up to create a new repository that only contains documentation. That's usually not what we want. Usually documentation is a part of a repository that also includes something else (which could be any of the other main templates, i.e. a backend add-on, a frontend add-on, or a project that includes both frontend and backend).

I'd like to see this become a subtemplate that is called in the post_gen_project hook of the other templates to add a docs directory (if the user answered yes to a question about whether they want documentation). If it also works as a standalone template, that's fine, but the subtemplate is the main thing we want. (@stevepiercy, yell at me if I'm on the wrong track here.)

The files in the top level {{cookiecutter.__folder_name}} folder will be a problem because they would overwrite files from the other templates. I'd suggest that we move the Makefile and README into the docs folder (so users will need to cd into that folder before running docs commands). @stevepiercy would you be okay with that? The alternative is figuring out a way to construct a Makefile that includes commands from all the subtemplates which were used, which is possible (maybe using mxmake) but complicated.

[stevepiercy]

First, I agree with the other comments that using addon in the name is wrong, because the thing it creates is not a Plone add-on. I would be okay with documentation_template or documentation_project as an alternative. (Or, open to other suggestions)

It's more of a foundation, platform, scaffold, base, or starter. It's not a project itself, but part of a project. Also since it's the result of being generated from a template, I don't want to reuse that term in its name.

I'd like to see this become a subtemplate that is called in the post_gen_project hook of the other templates to add a docs directory (if the user answered yes to a question about whether they want documentation). If it also works as a standalone template, that's fine, but the subtemplate is the main thing we want. (@stevepiercy, yell at me if I'm on the wrong track here.)

That's correct.

The files in the top level {{cookiecutter.__folder_name}} folder will be a problem because they would overwrite files from the other templates. I'd suggest that we move the Makefile and README into the docs folder (so users will need to cd into that folder before running docs commands). @stevepiercy would you be okay with that? The alternative is figuring out a way to construct a Makefile that includes commands from all the subtemplates which were used, which is possible (maybe using mxmake) but complicated.

Third option—and we did this in the unified Pyramid cookiecutter—include all possibilities, then delete those not selected. See https://github.com/Pylons/pyramid-cookiecutter-starter/blob/latest/hooks/post_gen_project.py.

[ujsquared]

I'm all done! This looks really good.

Do you have any further changes @ujsquared?

Let's get one more pass from the Cookieplone experts before we merge.

@davisagli @ericof @sneridagh

Just rewriting the tests specific to documentation_starter. Otherwise, we are all clear.

It looks like there are quite a few CI check failures. For example:

https://github.com/ujsquared/cookieplone-templates/actions/runs/14290696715/job/40051498986

I have fixed most of these tests in the new commits. Final commits to be pushed in an hour or two.

[stevepiercy]

Do we actually use templates/add-ons/documentation_starter/Makefile for testing?

[stevepiercy]

@davisagli @ericof @sneridagh is it OK to merge this PR? We're getting ready for World Plone Day on Thu, Apr 10, and this PR is critical.

See Storybook build error in frontend functional tests: https://github.com/ujsquared/cookieplone-templates/actions/runs/14296375658/job/40064081218

[ujsquared]

See Storybook build error in frontend functional tests: https://github.com/ujsquared/cookieplone-templates/actions/runs/14296375658/job/40064081218

I could reproduce this error on a volto-add-on created using the main branch too. The CI is somehow missing the storybook files. I could fuzzy find all *.mdx and *.storybook.@jsx/tsx files in core/ directory

[stevepiercy]

@ujsquared @sneridagh is on it. See #189 (comment). We'll merge that PR before this one, and continue.

[stevepiercy]

@ujsquared @sneridagh fixed the image, and I updated the branch. Now we wait for tests to run. It should be green soon.

We need a review from not-Steve and not-Ujjwal before merging.

[stevepiercy]

Watching closely: https://github.com/ujsquared/cookieplone-templates/actions/runs/14306067389/job/40090163130

[stevepiercy]

I think the status checks are not reporting correctly because @ujsquared's PR comes from a fork, not this repo. Nonetheless, all the checks pass.

[davisagli]

I tried it out and looked through the changes. Great work, @ujsquared and @stevepiercy!

I added some comments, but I think it's in a good place where we could go ahead and merge it and then do incremental improvements like normal.

[davisagli]

This is not high priority, but it'd be nice to update this to be more similar to the Makefiles for the other templates. (For example, use a "generate" command instead of "bake", and make it run cookieplone instead of cookiecutter.)

[stevepiercy]

Per my earlier comment, I'm not clear for what this Makefile is used. Does Cookieplone call its targets during the generation process, for tests, or something else? It's not really documented anywhere.

[davisagli]

On further inspection, I'm not sure either. I was thinking it was used by the github actions, but now I see they run commands from the top-level Makefile

[ujsquared]

If I remember correctly, the makefile is mostly borrowed over from plone-sphinx-theme. Hence the older cookie-cutter commands.

[stevepiercy]

There are two Makefiles per template.

• https://github.com/plone/cookieplone-templates/pull/174/files#diff-7d7002e7e946c75535a549438882fcf1b67651e9b0245bfc5989b340071626f7
• https://github.com/plone/cookieplone-templates/pull/174/files#diff-bbaac30402a0c9d35d50873dffdd1739eb344980a2b8fe8efaf193dd7554d956

The latter comes from PST. I have no clue where the former came from or what it does.

[stevepiercy]

@ujsquared can you restart the failed job from your fork? I don't have access to do so.

https://github.com/ujsquared/cookieplone-templates/actions/runs/14329161498/job/40160975816

It failed due to a temporary PyPI outage.

[ujsquared]

@stevepiercy can you pls add your name to co-author

@ujsquared can you restart the failed job from your fork? I don't have access to do so.

https://github.com/ujsquared/cookieplone-templates/actions/runs/14329161498/job/40160975816

It failed due to a temporary PyPI outage.

It's still failing due to the outage.

[stevepiercy]

@stevepiercy can you pls add your name to co-author

Done!

[ujsquared]

https://github.com/ujsquared/cookieplone-templates/actions/runs/14329161498/job/40181598975

all green!

[davisagli]

I'm going to go ahead and merge.