Reorganize repository with documentation that will be deployed with actions

[VisLab]

No description provided.

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved workflow permission, compatibility, documentation, and source-organization issues remain.

Review effort: Lite
Findings: 1 · 5

Open (6)

• Restrict deployment permissions to the deploy job · New
• Correct inconsistent changelog release date · New
• Move help block after MATLAB function declaration · New
• Correct plugin archive path and installation guidance · New
• Correct misspelled referenceChannels parameter · New
• Document the correct output handle for published reports · New

What changed in this PR

Adds a Sphinx documentation site with GitHub Pages deployment while reorganizing repository guidance, examples, and release metadata.

Changes:

• Adds user/API documentation, styling, and build tooling.
• Adds automated documentation deployment.
• Normalizes source files and removes obsolete examples/helpers.

File	Change	Review status
README.md	Documents documentation builds and publishing.	No specific finding.
pyproject.toml	Defines documentation dependencies.	No specific finding.
PrepPipeline/​utilities/​updateBadChannels.m	Normalizes formatting.	No specific finding.
PrepPipeline/​utilities/​struct2str.m	Normalizes formatting.	No specific finding.
PrepPipeline/​utilities/​robustReference.m	Normalizes formatting.	No specific finding.
PrepPipeline/​utilities/​getPrepVersion.m	Normalizes formatting.	No specific finding.
PrepPipeline/​utilities/​findNoisyChannels.m	Normalizes formatting.	No specific finding.
PrepPipeline/​utilities/​cleanLineNoise.m	Normalizes formatting.	No specific finding.
PrepPipeline/​utilities/​blasstLineNoise.m	Normalizes formatting.	No specific finding.
PrepPipeline/​reporting/​showPrepDefaults.m	Adds defaults display functionality.	Moderate issue: omits general defaults.
PrepPipeline/​publishPrepReport.m	Normalizes formatting.	No specific finding.
PrepPipeline/​preplicense.txt	Normalizes license text.	No specific finding.
PrepPipeline/​pop_prepPipeline.m	Normalizes formatting.	No specific finding.
PrepPipeline/​interface/​MasterGUI.m	Normalizes formatting.	No specific finding.
PrepPipeline/​interface/​displayErrors.m	Normalizes formatting.	No specific finding.
PrepPipeline/​examples/​runVEPPrepReport.m	Replaces machine-specific paths.	No specific finding.
PrepPipeline/​examples/​runVEPPrepPipeline.m	Replaces machine-specific paths.	No specific finding.
PrepPipeline/​examples/​runESSResampleAndDealias.m	Removes obsolete example.	No specific finding.
PrepPipeline/​examples/​runESSPrepPipeline.m	Removes obsolete example.	No specific finding.
PrepPipeline/​examples/​runESSLevel1ResampleAndDealias.m	Removes obsolete example.	No specific finding.
PrepPipeline/​eegplugin_prepPipeline.m	Normalizes formatting.	No specific finding.
PrepPipeline/​derived/​highPassAndICALinux.m	Removes Linux-specific helper.	Moderate issue: removes a public callable entry point without replacement or notice.
docs/​user_guide.md	Adds user documentation.	Nits: incorrect install path, output-handle description, parameter spelling/case, and return-value description.
docs/​patch_matlabdomain.py	Patches MATLAB-domain compatibility.	No specific finding.
docs/​index.rst	Adds documentation landing page.	No specific finding.
docs/​conf.py	Configures Sphinx and MATLAB documentation.	No specific finding.
docs/​api.rst	Adds API reference directives.	Nits: two entries lack extractable MATLAB help text.
docs/​_templates/​quicklinks.html	Adds documentation quick links.	No specific finding.
docs/​_static/​gh_icon_fix.js	Customizes GitHub links.	No specific finding.
docs/​_static/​custom.css	Adds documentation styling.	No specific finding.
CLAUDE.md	Adds Claude guidance pointer.	No specific finding.
CHANGELOG.md	Adds release history.	Nit: 0.57.0 release date conflicts with version metadata.
AGENTS.md	Adds repository instructions.	No specific finding.
.vscode/​settings.json	Adds editor settings.	No specific finding.
.gitignore	Ignores local tooling artifacts.	No specific finding.
.github/​workflows/​deploy-docs.yaml	Builds and deploys GitHub Pages documentation.	Critical issue: build job inherits deployment and OIDC write permissions while executing PR-controlled code.
.github/​instructions/​status_conduct.instructions.md	Adds scoped status guidance.	No specific finding.
.github/​copilot-instructions.md	Adds Copilot guidance.	No specific finding.
.gitattributes	Defines line-ending and binary handling.	No specific finding.
.claude/​settings.json	Configures Claude permissions.	No specific finding.
.claude/​rules/​status_conduct.md	Adds Claude status rules.	Nit: duplicates the GitHub instruction source instead of using one canonical source.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved critical command-permission exposure and additional documentation and reporting issues remain.

Review effort: Lite
Findings: 1

Open (1)

• Broad shell allow rules can expose secrets · New

Resolved since last review (6)

• Restrict deployment permissions to the deploy job
• Document the correct output handle for published reports
• Correct misspelled referenceChannels parameter
• Correct plugin archive path and installation guidance
• Move help block after MATLAB function declaration
• Correct inconsistent changelog release date

Previously missed (5)

In code that hasn't changed since last review

API documentation omits showPrepDefaults

docs/​api.rst:38

The API page claims to document the public entry points, but it omits the newly added reporting.showPrepDefaults function while listing the older defaults printer. Users following the published API will not discover the function referenced by prepPipeline's help text.

Correct misspelling of embarrassingly

docs/​user_guide.md:31

embarassingly is misspelled in this new user-guide text; use embarrassingly.

This issue also appears in the following locations of the same file:

• line 107
• line 199

Mismatched Markdown delimiters around robust

docs/​user_guide.md:254

The robust inline literal starts with two backticks but closes with a single backtick after an apostrophe, so the generated page will render this markup incorrectly. Use matching Markdown delimiters around robust.

Document skipReport instead of unsupported skip

docs/​user_guide.md:329

The implementation accepts skipReport (see reportGUI.m and the three strcmpi checks in pop_prepPipeline.m), not skip. Following this new guide and passing reportMode = 'skip' therefore matches none of the execution branches and runs neither PREP nor reporting; document the actual skipReport value.

Heading does not match publishOn parameter

docs/​user_guide.md:359

This heading does not match the public parameter name (publishOn) used by publishPrepReport and by the surrounding text. Keep the documented spelling/casing consistent so users can map the option to the function signature.

[Copilot]

Copilot review overview

🟡 Changes recommended

The default example references absent datasets, and several newly published API instructions are inaccurate.

Review effort: Balanced
Findings: 2 · 5

Open (7)

• Missing bundled recordings make the example silently process no inputs · New
• Setuptools minimum version is incompatible with PEP 621 metadata · New
• Licensing row references absent example data · New
• Documentation incorrectly describes the default report behavior · New
• Documented cleanLineNoise call fails without lineNoiseIn · New
• Documented channelInfo parameter does not match channelInformation · New
• publishPrepReport documentation promises a nonexistent return value · New

Resolved since last review (1)

• Broad shell allow rules can expose secrets

[Copilot]

Copilot review overview

🔵 Needs a closer look

The defaults reporter has incomplete output, release dates and iteration documentation are inaccurate, and the plugin licensing table omits bundled BLASST code.

Review effort: Balanced
Findings: None

Resolved since last review (7)

• Setuptools minimum version is incompatible with PEP 621 metadata
• Missing bundled recordings make the example silently process no inputs
• publishPrepReport documentation promises a nonexistent return value
• Documented channelInfo parameter does not match channelInformation
• Documented cleanLineNoise call fails without lineNoiseIn
• Documentation incorrectly describes the default report behavior
• Licensing row references absent example data

Previously missed (2)

In code that hasn't changed since last review

Add BLASST to the plugin license table

README.md:96

The released 0.57.0 plugin still contains utilities/blasst/ and blasstLineNoise.m, whose headers license BLASST under Apache-2.0, but the table says the zip is covered by the components above and no longer lists BLASST. Add a plugin-only BLASST row so users can determine the license of every file currently distributed in the latest release.

Enforce the stated maximum reference iterations

docs/​user_guide.md:324

The implementation checks iterations > maxReferenceIterations before each pass, so with the default of 4 a non-converging run performs five iterations and records actualReferenceIterations = 5. Either change the loop guard to enforce four as the maximum or document the current off-by-one behavior; the stated maximum is not currently accurate.