Aim 1.5: Documentation Website

[pauladkisson]

Documentation plan for GuPPy v2

GuPPy v2 has no hosted documentation. The GitHub Wiki covers v1.3.0 workflows but is not being updated for v2, and there is no API reference or conceptual background for new users. This issue tracks the full documentation effort using the Diataxis framework (Tutorials, How-to, Explanation, Reference) on a Read the Docs site built with Sphinx and MyST-Parser. The site is divided into user documentation and a contributing guide so that developer-facing content does not clutter the user experience.

User documentation

Homepage

• Update the home page with all of the information from the README (ex. installation). (Rework the docs home page into a graphical launch point #444)
• Update the README to simply point to docs for documentation (Rework the docs home page into a graphical launch point #444)
• Update the home page to have a clean graphical launch point like NumPy (Rework the docs home page into a graphical launch point #444)
• Update branding (Swap in the new GuPPy logo and add a favicon #445)

Tutorials

• Infrastructure: Sphinx + pydata-sphinx-theme + MyST-Parser + Read the Docs config (Add documentation site with Sphinx and a first tutorial #264)
• First tutorial: end-to-end GUI walkthrough using stubbed CSV data (Add documentation site with Sphinx and a first tutorial #264)
• Add screenshots to the first tutorial (Add content to first tutorial #303)
• Loading GuPPy outputs in Python (Add a tutorial for loading GuPPy outputs in Python #421)

Explanation

• Z-score normalization (Add z-score normalization explanation page #308)
• Cross-correlation (Add cross-correlation explanation page #307)
• Fiber photometry (Add fiber photometry explainer #319)
• PSTH (Add PSTH explanation page #315)
• Isosbestic correction (Add isosbestic explainer #324)
• Transient detection (Add transient detection explainer #332)
• Artifacts orientation page (Add artifacts explainer #334)

How-to guides

• How to remove artifacts (Split artifact removal into two optional steps #413)
• How to run group analysis (Add how-to guide for group analysis #435)
• How to combine data (Add how-to guide for combining split session data #436)
• How to analyze data from dandi (Add how-to guide for analyzing data streamed from DANDI #437)
• How to compare multiple parameter choices on the same session (Add tutorial for comparing parameter choices on one session #438)

Reference

• Parameter reference (Documentation. Add parameters reference #341)
• Output data model (Document the GuPPy output data model #418)

Contributing guide

• How to set up a development environment (Add development environment page to contributor's guide #431)
• How to run the test suite (Add contributor testing guide #432)
• How to contribute a new recording format (Add contributor guide for adding a new acquisition format #434)
• Pipeline architecture (HDF5 intermediates, subprocess model, frontend/backend split) (Add a Contributor's Guide section with an architecture overview #428)

Infrastructure

• Connect the Read the Docs project to the repository (requires repo admin access)

[h-mayorquin]

This is what I have on mind:

Documentation plan for GuPPy v2

GuPPy v2 has no hosted documentation. The GitHub Wiki covers v1.3.0 workflows but is not being updated for v2, and there is no API reference or conceptual background for new users. This issue tracks the full documentation effort using the Diataxis framework (Tutorials, How-to, Explanation, Reference) on a Read the Docs site built with Sphinx and MyST-Parser. The site is divided into user documentation and a contributing guide so that developer-facing content does not clutter the user experience.

User documentation

Tutorials

• Infrastructure: Sphinx + pydata-sphinx-theme + MyST-Parser + Read the Docs config (Add documentation site with Sphinx and a first tutorial #264)
• First tutorial: end-to-end GUI walkthrough using stubbed CSV data (Add documentation site with Sphinx and a first tutorial #264)
• Add screenshots to the first tutorial (Add content to first tutorial #303)

Explanation

• Z-score normalization (Add z-score normalization explanation page #308)
• Cross-correlation (Add cross-correlation explanation page #307)
• Fiber photometry (Add fiber photometry explainer #319)
• PSTH (Add PSTH explanation page #315)
• Isosbestic correction (Add isosbestic explainer #324)
• Transient detection (Add transient detection explainer #332)
• Artifacts orientation page (Add artifacts explainer #334)

How-to guides

• How to remove artifacts: Split artifact removal into two optional steps #413
• How to run group analysis
• How to combine data

Reference

• Parameter reference Documentation. Add parameters reference #341

Contributing guide

• How to set up a development environment
• How to run the test suite
• How to contribute a new recording format
• Pipeline architecture (HDF5 intermediates, subprocess model, frontend/backend split)
• Design decisions and extension points

Infrastructure

• Connect the Read the Docs project to the repository (requires repo admin access)

[DRZ-cloud]

It would be really helpful to add a section on cross-correlation, how it is calculated, and background of the measure.

[h-mayorquin]

It would be really helpful to add a section on cross-correlation, how it is calculated, and background of the measure.

#307

It can be read here:
https://guppy--307.org.readthedocs.build/explanation/cross_correlation.html

[DRZ-cloud]

Thank you, this is extremely helpful!

[h-mayorquin]

Discussed with @pauladkisson today, we both agree that probably the how-tos per format do not make a lot of sense besides NPM which is maybe better served by other means.

[pauladkisson]

Downgrading #342 as a potential follow-up instead of a blocking sub-issue. To be honest, I think git LFS works well enough for the data that we have, and if we get complaints from users that it's too complicated, then we can revisit the issue at that time.