Treat generated docs as build artifacts

[dcajal]

This pull request updates the documentation build workflow and clarifies the documentation generation process. It removes all auto-generated API and example Markdown files from version control, updates documentation guidelines, and improves the CI workflow to handle documentation generation and deployment more robustly. The most important changes are summarized below.

Documentation build workflow and CI improvements:

• The documentation build workflow in .github/workflows/docs.yaml now runs on both pushes and pull requests targeting main, ensuring docs are always regenerated in CI. It also prevents deployment and artifact upload steps from running on pull requests, and switches the MATLAB script path from scripts/local to scripts/docs for doc generation. [1] [2] [3]
• The documentation guidelines in AGENTS.md are updated to clarify that generated API/example Markdown files are build artifacts and should not be committed. CI is responsible for regenerating these files before building the docs.
• The README.md is updated to explain that API and example reference pages are generated from MATLAB headers and example source files during the documentation build.

Removal of generated documentation from version control:

• All generated API and example Markdown files are removed from the repository, including docs/api/ecg/baselineremove.md, docs/api/ecg/pantompkins.md, docs/api/ecg/sloperange.md, docs/api/ecg/index.md, docs/api/hrv/fdmetrics.md, docs/api/hrv/fillgaps.md, docs/api/hrv/ipfm.md, docs/api/hrv/osp.md, docs/api/hrv/removefp.md, docs/api/hrv/tdmetrics.md, and docs/api/hrv/index.md. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11]

These changes ensure that generated documentation is always up-to-date, reduce merge conflicts, and clarify the contribution process for documentation updates.

[Copilot]

Pull request overview

This PR changes the documentation workflow so generated API/example Markdown under docs/api/ and docs/examples/ is treated as a build artifact rather than committed source, with CI regenerating docs before running mkdocs build --strict.

Changes:

• Update scripts/docs/updateDocs.m to purge previously generated Markdown before regenerating docs from MATLAB headers/examples.
• Adjust CI docs workflow to regenerate docs on both push and pull_request (while skipping deploy/artifact upload on PRs), and update contributor guidance accordingly.
• Remove generated API/example Markdown files from version control and add Git ignore rules for regenerated content.

Reviewed changes

Copilot reviewed 58 out of 59 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
scripts/docs/updateDocs.m	Adds a cleanup step to remove generated Markdown before regenerating docs.
README.md	Notes that API/example reference pages are generated during the docs build.
docs/examples/tidalvolumeExample.md	Removes generated example page (now treated as build output).
docs/examples/tfmapWorkflow.md	Removes generated workflow page (now treated as build output).
docs/examples/tdmetricsExample.md	Removes generated example page (now treated as build output).
docs/examples/sloperangeExample.md	Removes generated example page (now treated as build output).
docs/examples/removefpExample.md	Removes generated example page (now treated as build output).
docs/examples/pulseenvelopesExample.md	Removes generated example page (now treated as build output).
docs/examples/pulsedetectionExample.md	Removes generated example page (now treated as build output).
docs/examples/pulsedelineationExample.md	Removes generated example page (now treated as build output).
docs/examples/pcaverageWorkflow.md	Removes generated workflow page (now treated as build output).
docs/examples/pantompkinsExample.md	Removes generated example page (now treated as build output).
docs/examples/ospExample.md	Removes generated example page (now treated as build output).
docs/examples/ipfmExample.md	Removes generated example page (now treated as build output).
docs/examples/index.md	Removes generated examples index page (now treated as build output).
docs/examples/hjorthArtifactsExample.md	Removes generated example page (now treated as build output).
docs/examples/fillgapsExample.md	Removes generated example page (now treated as build output).
docs/examples/fdmetricsExample.md	Removes generated example page (now treated as build output).
docs/examples/baselineremoveExample.md	Removes generated example page (now treated as build output).
docs/contribute/contribution-guide.md	Adds explicit guidance that generated docs are ignored by Git and rebuilt in CI.
docs/api/tools/trimnans.md	Removes generated API page (now treated as build output).
docs/api/tools/snaptopeak.md	Removes generated API page (now treated as build output).
docs/api/tools/slider.md	Removes generated API page (now treated as build output).
docs/api/tools/slicesignal.md	Removes generated API page (now treated as build output).
docs/api/tools/peakedness.md	Removes generated API page (now treated as build output).
docs/api/tools/nanpwelch.md	Removes generated API page (now treated as build output).
docs/api/tools/nanfiltfilt.md	Removes generated API page (now treated as build output).
docs/api/tools/nanfilter.md	Removes generated API page (now treated as build output).
docs/api/tools/medfiltThreshold.md	Removes generated API page (now treated as build output).
docs/api/tools/lpdfilter.md	Removes generated API page (now treated as build output).
docs/api/tools/localmax.md	Removes generated API page (now treated as build output).
docs/api/tools/ispeaky.md	Removes generated API page (now treated as build output).
docs/api/tools/interpgap.md	Removes generated API page (now treated as build output).
docs/api/tools/index.md	Removes generated module index page (now treated as build output).
docs/api/tools/hjorth.md	Removes generated API page (now treated as build output).
docs/api/tools/findsequences.md	Removes generated API page (now treated as build output).
docs/api/tools/expandnans.md	Removes generated API page (now treated as build output).
docs/api/resp/tidalvolume.md	Removes generated API page (now treated as build output).
docs/api/resp/index.md	Removes generated module index page (now treated as build output).
docs/api/ppg/pulseenvelopes.md	Removes generated API page (now treated as build output).
docs/api/ppg/pulsedetection.md	Removes generated API page (now treated as build output).
docs/api/ppg/pulsedelineation.md	Removes generated API page (now treated as build output).
docs/api/ppg/index.md	Removes generated module index page (now treated as build output).
docs/api/ppg/hjorthArtifacts.md	Removes generated API page (now treated as build output).
docs/api/index.md	Removes generated API landing page (now treated as build output).
docs/api/hrv/tdmetrics.md	Removes generated API page (now treated as build output).
docs/api/hrv/removefp.md	Removes generated API page (now treated as build output).
docs/api/hrv/osp.md	Removes generated API page (now treated as build output).
docs/api/hrv/ipfm.md	Removes generated API page (now treated as build output).
docs/api/hrv/index.md	Removes generated module index page (now treated as build output).
docs/api/hrv/fillgaps.md	Removes generated API page (now treated as build output).
docs/api/hrv/fdmetrics.md	Removes generated API page (now treated as build output).
docs/api/ecg/sloperange.md	Removes generated API page (now treated as build output).
docs/api/ecg/pantompkins.md	Removes generated API page (now treated as build output).
docs/api/ecg/index.md	Removes generated module index page (now treated as build output).
docs/api/ecg/baselineremove.md	Removes generated API page (now treated as build output).
AGENTS.md	Updates contributor rules to point to scripts/docs/updateDocs.m and clarify generated Markdown is not committed.
.gitignore	Ignores generated Markdown under docs/api/ and docs/examples/.
.github/workflows/docs.yaml	Runs docs generation on PRs and pushes; skips deploy/artifact upload on PRs; uses scripts/docs.

Comments suppressed due to low confidence (1)

scripts/docs/updateDocs.m:99

• cleanGeneratedDocs deletes generated Markdown files without handling I/O errors. If any file is read-only/locked or delete fails for another reason, the entire docs build will abort, causing CI to fail even though regeneration could continue. Consider wrapping delete in a per-file try/catch and emitting a warning so the docs build is more resilient.