Add ChRIS plugin creation guide

[rudolphpienaar]

Adds a contributor-facing guide for creating ChRIS plugins. The page documents the current python-chrisapp-template workflow, manual and bootstrap initialization paths, GitHub Actions and publication assumptions, ChRIS registration prerequisites, and the future plugin factory direction.

Validation:

• pnpm run build (passes; existing warnings remain for blog truncation markers and /blog/2025/08/03/preact-tooling#farm-and-preact)

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

AI Reviewer: first review requested successfully. AI can make mistakes. Always validate suggestions.

_{TIP This summary will be updated as you push new changes.}

[codacy-production]

Pull Request Overview

The PR introduces a comprehensive guide for creating ChRIS plugins, including initialization, CI/CD configuration, and registration steps. The content aligns well with the intended scope and correctly links the new guide into the existing documentation structure.

However, a significant documentation gap was identified regarding the main function signature. The current draft only provides the signature for 'ds' (data synthesis) plugins. As 'fs' (feed synthesis) plugins are a core component of the ecosystem, this omission could lead to runtime failures for developers. Resolving this discrepancy is recommended before merging to ensure the guide is technically accurate for all standard use cases.

Codacy analysis indicates the changes are up to standards with no new quality issues or complexity regressions.

Test suggestions

• Verify that 'pnpm run build' completes successfully with the new content.
• Ensure the relative link from docs/plugins/index.md correctly points to the new create.md file.
• Confirm that relative tutorial links (e.g., ../tutorials/upload_plugin/) within the new guide resolve correctly.

_{TIP Improve review quality by adding custom instructions
TIP How was this review? Give us feedback}

[codacy-production]

_{🟡 MEDIUM RISK}

The signature main(options, inputdir, outputdir) is specific to ds type plugins. For fs plugins, the inputdir argument must be omitted. Since 'fs' plugins are a core plugin type described in the documentation, it is important to clarify this requirement to prevent runtime failures.

Try running the following prompt in your coding agent:

In docs/plugins/create.md, add a note explaining that while 'ds' plugins use main(options, inputdir, outputdir), 'fs' plugins must use the signature main(options, outputdir).

[codacy-production]

_{⚪ LOW RISK}

Nitpick: Link styles are inconsistent across the file (e.g., ../tutorials/convert_python_app.md vs ../tutorials/upload_plugin/). Use a consistent format for all tutorial references.

[jbernal0019]

@rudolphpienaar

Accurate and well-organized; no build-breaking issues. All internal links resolve (../tutorials/upload_plugin/ points at the existing upload_plugin/index.md), so the pnpm build claim holds. Some items mentioned below could be improved before merge — they are clarity/correctness, not blockers.

The PR documents the main undocumented gotcha: the CI ships disabled by default (if: false). The
"GitHub Actions and Publication" section states the workflow ships with if: false guards and that bootstrap.sh or a manual edit removes them. The "undocumented" half of the issue is resolved.

However three weaknesses keep it from fully landing:

• It's buried in prose. This is the single most common "why isn't my plugin building" trap. Promote it to a :::caution admonition so a skimming reader cannot miss it — the repo already uses admonitions (convert_python_app.md).
• The manual-init walkthrough never mentions it. A reader following "Manual initialization" edits app.py/setup.py/Dockerfile/tests, pushes, and sees nothing happen — the if: false note only appears two sections later. Add a pointer in the manual path.
• "parts of the workflow are disabled" understates it. In the current template both the test and build jobs carry if: false; a freshly templated repo's CI does effectively nothing. Say that, and give the concrete fix — "delete the if: false line" (the template ships that exact comment) — instead of the vague "edit the workflow manually."

Improvements

• Add concrete commands. "Before publishing, run the plugin locally … build the container image and run the command" tells the reader to do something without showing how. Include the actual docker build and docker run -v in:/incoming -v out:/outgoing … invocation, and the pytest-in-container command. A how-to page should be copy-pasteable.
• pf_build. The "Existing Template and Factory Status" section names pf_build as a POC with no link. If it is a public repo, link it; if it is internal/unreleased, do not name it in a public contributor guide — an external reader cannot find or act on it. Describe the capability generically instead.

Structure / scope

• The page is a how-to entry point, but its second half (Existing Template and Factory Status, What Remains Manual, Future: Plugin Factory) is roadmap and meta-commentary. That dilutes the actionable content and will age faster than the how-to. Trim to a short "Status and future" note that links to a roadmap/design page, and keep create.md focused on creating a plugin today.
• Use admonitions for the remaining caveats too — bootstrap.sh being GNU/Linux-only, and the registration prerequisites (admin account + compute resource) — consistent with convert_python_app.md.
• The "ChRIS Registration" section overlaps with the existing tutorials/upload_plugin/ page. Keep it as a brief lead-in that defers to that page (it already links there) rather than re-explaining chris_plugin_info.

Nits

• create.md carries both frontmatter title: and an identical # H1. Sibling convert_python_app.md uses frontmatter title: only — pick one for consistency.
• Double blank line before ## Future: Plugin Factory.
• Mixed link style — ./github_actions.md (file form) vs ../tutorials/upload_plugin/ (path form). Both resolve; prefer the .md file form throughout so links are validated by onBrokenMarkdownLinks and survive page refactors.
• No sidebar_position on create.md; it currently sorts first only by alphabetical accident. Set it explicitly.