Docs first version

[jcharkow]

User description

Initial commit for documentation. Will merge with main branch in order to test directly with readthedocs

---

PR Type

Documentation, Enhancement

---

Description

• Added comprehensive documentation for PyOpenMS-Viz using Sphinx, including configuration, examples, and user guides.
• Implemented error handling in gallery script examples for robust file downloading.
• Enhanced plotting functions across Bokeh, Matplotlib, and Plotly backends to conditionally display plots based on context.
• Introduced custom CSS for improved documentation styling and added version switcher configuration.
• Provided detailed installation, testing, and usage instructions in the documentation.

---

Changes walkthrough 📝

	Relevant files
Documentation	25 files conf.py Add Sphinx configuration and gallery script setup                docs/conf.py Added Sphinx configuration for documentation generation. Configured gallery scripts for different backends. Implemented custom Bokeh scraper for documentation. +241/-0  plot_chromatogram.py Add chromatogram plotting example with error handling        docs/gallery_scripts_template/plot_chromatogram.py Added example for plotting chromatograms. Implemented error handling for file download. +34/-0    plot_investigate_spectrum_binning_ms_matplotlib.py Add spectrum binning investigation example                              docs/gallery_scripts_template/plot_investigate_spectrum_binning_ms_matplotlib.py Added example for investigating spectrum binning. Implemented error handling for file download. +59/-0    plot_mobilogram.py Add mobilogram plotting example with error handling            docs/gallery_scripts_template/plot_mobilogram.py Added example for plotting mobilograms. Implemented error handling for file download. +35/-0    plot_peakmap.py Add peak map plotting example with error handling                docs/gallery_scripts_template/plot_peakmap.py Added example for plotting peak maps. Implemented error handling for file download. +35/-0    plot_peakmap_marginals.py Add peak map with marginals example                                            docs/gallery_scripts_template/plot_peakmap_marginals.py Added example for plotting peak maps with marginals. Implemented error handling for file download. +35/-0    plot_spectrum_dia.py Add DIA spectrum plotting example                                                docs/gallery_scripts_template/plot_spectrum_dia.py Added example for plotting DIA spectrum. Implemented error handling for file download. +38/-0    API.rst Add API documentation for PyOpenMS-Viz                                      docs/API.rst Added API documentation for core and extension modules. Included autosummary and autodoc directives. +175/-0  Chromatogram.rst Document chromatogram plotting with examples                          docs/Chromatogram.rst Added documentation for chromatogram plotting. Included example usage with gallery scripts. +23/-0    Installation.rst Add installation instructions for PyOpenMS-Viz                      docs/Installation.rst Added installation instructions for PyOpenMS-Viz. Included steps for building from source. +45/-0    Mobilogram.rst Document mobilogram plotting with examples                              docs/Mobilogram.rst Added documentation for mobilogram plotting. Included example usage with gallery scripts. +23/-0    PeakMap.rst Document peak map plotting with examples                                  docs/PeakMap.rst Added documentation for peak map plotting. Included example usage with gallery scripts. +31/-0    README.md Add README for documentation setup and contribution            docs/README.md Added README for building and adding documentation. Included instructions for local documentation setup. +27/-0    Spectrum.rst Document spectrum plotting with examples                                  docs/Spectrum.rst Added documentation for spectrum plotting. Included example usage with gallery scripts. +28/-0    Testing.rst Add testing instructions for PyOpenMS-Viz                                docs/Testing.rst Added testing instructions using Pytest and Syrupy. Included setup and running test commands. +47/-0    User Guide.rst Add user guide for PyOpenMS-Viz plotting                                  docs/User Guide.rst Added user guide for PyOpenMS-Viz plotting. Included supported plot types and options. +18/-0    custom.css Add custom CSS for documentation styling                                  docs/_static/custom.css Added custom CSS for documentation styling. Included styles for video admonitions and tooltips. +168/-0  switcher.json Add version switcher configuration                                              docs/_static/switcher.json Added version switcher configuration for documentation. +6/-0      GALLERY_HEADER.rst Add gallery header for plot examples                                          docs/gallery_scripts_template/GALLERY_HEADER.rst Added gallery header for plot examples. +4/-0      GALLERY_HEADER_ms_bokeh.rst Add gallery header for Bokeh plots                                              docs/gallery_scripts_template/GALLERY_HEADER_ms_bokeh.rst Added gallery header for Bokeh plots. +4/-0      GALLERY_HEADER_ms_matplotlib.rst Add gallery header for Matplotlib plots                                    docs/gallery_scripts_template/GALLERY_HEADER_ms_matplotlib.rst Added gallery header for Matplotlib plots. +4/-0      GALLERY_HEADER_ms_plotly.rst Add gallery header for Plotly plots                                            docs/gallery_scripts_template/GALLERY_HEADER_ms_plotly.rst Added gallery header for Plotly plots. +4/-0      index.rst Add index for PyOpenMS-Viz documentation                                  docs/index.rst Added index for PyOpenMS-Viz documentation. Included quick start and user guide sections. +71/-0    requirements.txt Add requirements for documentation build                                  docs/requirements.txt Added requirements for building documentation. +8/-0      class.rst Add template for class documentation                                          docs/templates/class.rst Added template for class documentation. +16/-0
Enhancement	7 files __init__.py Update Bokeh plot function for conditional display              pyopenms_viz/_bokeh/init.py Modified plot function to return figure or show plot. +4/-1      core.py Enhance Bokeh core with context-aware show methods              pyopenms_viz/_bokeh/core.py Added show methods for different contexts. Improved plot aesthetics and legend handling. +27/-14  _core.py Enhance core plotting with Sphinx build context                    pyopenms_viz/_core.py Added IS_SPHINX_BUILD constant for context-aware plotting. Improved plot generation and data binning methods. +68/-39  __init__.py Update Matplotlib plot function for conditional display    pyopenms_viz/_matplotlib/init.py Modified plot function to return figure or show plot. +4/-1      core.py Enhance Matplotlib core with improved plot handling            pyopenms_viz/_matplotlib/core.py Enhanced figure creation and plot display methods. Improved handling of plot aesthetics and annotations. +85/-44  __init__.py Update Plotly plot function for conditional display            pyopenms_viz/_plotly/init.py Modified plot function to return figure or show plot. +4/-1      core.py Enhance Plotly core with context-aware show methods            pyopenms_viz/_plotly/core.py Added show methods for different contexts. Enhanced plot generation and tooltip handling. +101/-53

---

💡 PR-Agent usage: Comment /help "your question" on any pull request to receive relevant information

[qodo-code-review]

PR-Agent was enabled for this repository. To continue using it, please link your git user with your CodiumAI identity here.

PR Reviewer Guide 🔍

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Key issues to review Code Duplication There are several instances of repeated code blocks across different plot types (e.g., in ChromatogramPlot, MobilogramPlot, SpectrumPlot). Consider refactoring common functionality into shared methods or a base class. Error Handling The error handling for the 'z' parameter in the PLOTLYVLinePlot.plot method could be improved. Currently, it silently ignores the case where 'z' is not provided, which might lead to unexpected behavior. Configuration Complexity The configuration file is quite long and complex. Consider breaking it down into smaller, more manageable sections or separate files for better maintainability.

[qodo-code-review]

PR-Agent was enabled for this repository. To continue using it, please link your git user with your CodiumAI identity here.

PR Code Suggestions ✨

Category	Suggestion	Score
Enhancement	✅ Update installation instructions to use the correct package name and environment name Suggestion Impact: The suggestion impacted the commit by changing the environment activation command to use 'pyopenms-viz' instead of 'massdash'. code diff: - conda create --name=massdash python=3.9 - conda activate massdash + conda create --name=massdash python=3.11 + conda activate pyopenms-viz Update the installation instructions to use the correct package name 'pyopenms-viz' instead of 'massdash'. docs/Installation.rst [7-20] -The recommended way of installing MassDash is through the Python Package Index (PyPI). We recommend installing MassDash in its own virtual environment using Anaconda to avoid packaging conflicts. +The recommended way of installing PyOpenMS-Viz is through the Python Package Index (PyPI). We recommend installing PyOpenMS-Viz in its own virtual environment using Anaconda to avoid packaging conflicts. First create a new environment: .. code-block:: bash - conda create --name=massdash python=3.9 - conda activate massdash + conda create --name=pyopenms-viz python=3.9 + conda activate pyopenms-viz -Then in the new environment install MassDash. +Then in the new environment install PyOpenMS-Viz. .. code-block:: bash - pip install pyopenmsviz --upgrade + pip install pyopenms-viz --upgrade Apply this suggestion Suggestion importance[1-10]: 9 Why: The suggestion corrects the package and environment names, which is crucial for users to successfully install the software, thus addressing a significant usability issue.	9
	Update testing instructions to use the correct project name in the command path Update the testing instructions to use the correct project name 'pyopenms-viz' instead of 'massdash'. docs/Testing.rst [28-32] -To run the tests, execute the following command in the `massdash/` base folder: +To run the tests, execute the following command in the `pyopenms-viz/` base folder: .. code-block:: bash python -m pytest --snapshot-warn-unused test/ Apply this suggestion Suggestion importance[1-10]: 9 Why: This suggestion corrects the project name in the testing instructions, which is essential for users to execute tests correctly, thereby resolving a critical documentation error.	9
	✅ Remove duplicate entry and add missing PLOTLYVLinePlot in the PLOTLY Simple Plots section Suggestion Impact: The suggestion was directly implemented by removing the duplicate entry for PLOTLYLinePlot and adding the missing PLOTLYVLinePlot entry in the PLOTLY Simple Plots section. code diff: PLOTLYLinePlot - PLOTLYLinePlot + PLOTLYVLinePlot Remove the duplicate entry for PLOTLYLinePlot in the Simple Plots section under the PLOTLY extension. docs/API.rst [115-117] PLOTLYLinePlot -PLOTLYLinePlot +PLOTLYVLinePlot PLOTLYScatterPlot Apply this suggestion Suggestion importance[1-10]: 8 Why: The suggestion correctly identifies and addresses a duplicate entry in the documentation, improving clarity and accuracy by adding the missing PLOTLYVLinePlot entry.	8
	✅ Remove duplicate entry and add missing MATPLOTLIBVLinePlot in the MATPLOTLIB Simple Plots section Suggestion Impact: The suggestion was implemented by removing the duplicate entry for MATPLOTLIBLinePlot and adding MATPLOTLIBVLinePlot in the Simple Plots section under the MATPLOTLIB extension. code diff: @@ -156,7 +156,7 @@ :template: class.rst MATPLOTLIBLinePlot - MATPLOTLIBLinePlot + MATPLOTLIBVLinePlot MATPLOTLIBScatterPlot Remove the duplicate entry for MATPLOTLIBLinePlot in the Simple Plots section under the MATPLOTLIB extension. docs/API.rst [158-160] MATPLOTLIBLinePlot -MATPLOTLIBLinePlot +MATPLOTLIBVLinePlot MATPLOTLIBScatterPlot Apply this suggestion Suggestion importance[1-10]: 8 Why: This suggestion accurately removes a duplicate entry and adds a missing entry, enhancing the documentation's accuracy and completeness.	8
	Simplify the creation of vertex lists using list extension methods Consider using a dictionary comprehension instead of a loop to create the z_vert list. This can make the code more concise and potentially more efficient. pyopenms_viz/_plotly/core.py [331-340] -for i in range(2): - x_vert.append(x_val) - y_vert.append(y_val) - if i == 0: - z_vert.append(0) - else: - z_vert.append(z_val) -x_vert.append(None) -y_vert.append(None) -z_vert.append(None) +x_vert.extend([x_val, x_val, None]) +y_vert.extend([y_val, y_val, None]) +z_vert.extend([0, z_val, None]) Apply this suggestion Suggestion importance[1-10]: 7 Why: The suggestion to use list extension methods simplifies the code and improves readability without altering functionality. However, the performance gain is minimal, so it's a minor enhancement.	7
	Simplify the renderer selection and direction assignment using ternary operators Consider using a ternary operator to simplify the assignment of the direction variable. This can make the code more concise and easier to read. pyopenms_viz/_core.py [1128-1142] -if self.y_kind in ["chromatogram", "mobilogram"]: - y_plot_obj = self.get_line_renderer( - y_data, z, y, by=self.by, _config=y_config, **class_kwargs - ) - y_fig = y_plot_obj.generate(line_color=color_gen) -elif self.y_kind == "spectrum": - direction = "horizontal" - y_plot_obj = self.get_vline_renderer( - y_data, z, y, by=self.by, _config=y_config, **class_kwargs - ) +renderer = self.get_line_renderer if self.y_kind in ["chromatogram", "mobilogram"] else self.get_vline_renderer +direction = "horizontal" if self.y_kind == "spectrum" else None + +if renderer: + y_plot_obj = renderer(y_data, z, y, by=self.by, _config=y_config, **class_kwargs) y_fig = y_plot_obj.generate(line_color=color_gen, direction=direction) else: raise ValueError( f"y_kind {self.y_kind} not recognized, must be 'chromatogram', 'mobilogram' or 'spectrum'" ) Apply this suggestion Suggestion importance[1-10]: 7 Why: The use of ternary operators simplifies the code and improves readability. It is a minor enhancement but contributes to cleaner code structure.	7
	Simplify the color list creation for 3D scatter plot using a more concise list comprehension Consider using a list comprehension instead of a loop to create the color list for the 3D scatter plot. This can make the code more concise and potentially more efficient. pyopenms_viz/_plotly/core.py [348-354] line=dict( width=5, - color=[z if z is not None else 0 for z in z_vert], + color=[z or 0 for z in z_vert], colorscale="magma_r", cmin=z_min, cmax=z_max, ), Apply this suggestion Suggestion importance[1-10]: 6 Why: The suggestion offers a slightly more concise way to write the list comprehension, improving readability. The performance impact is negligible, making it a minor enhancement.	6
Maintainability	Use a dictionary to map x_kind values to renderer methods for improved maintainability Consider using a dictionary to map x_kind values to their corresponding renderer methods. This can make the code more maintainable and easier to extend in the future. pyopenms_viz/_core.py [1089-1100] -if self.x_kind in ["chromatogram", "mobilogram"]: - x_plot_obj = self.get_line_renderer( - x_data, x, z, by=self.by, _config=x_config, **class_kwargs - ) -elif self.x_kind == "spectrum": - x_plot_obj = self.get_vline_renderer( - x_data, x, z, by=self.by, _config=x_config, **class_kwargs - ) +renderer_map = { + "chromatogram": self.get_line_renderer, + "mobilogram": self.get_line_renderer, + "spectrum": self.get_vline_renderer, +} +renderer = renderer_map.get(self.x_kind) +if renderer: + x_plot_obj = renderer(x_data, x, z, by=self.by, _config=x_config, **class_kwargs) else: raise ValueError( f"x_kind {self.x_kind} not recognized, must be 'chromatogram', 'mobilogram' or 'spectrum'" ) Apply this suggestion Suggestion importance[1-10]: 8 Why: Using a dictionary to map x_kind values to renderer methods enhances maintainability and scalability of the code, making it easier to extend in the future. This is a significant improvement in terms of code organization.	8
	Extract repeated color setting logic into a separate method to reduce code duplication Consider extracting the repeated color setting logic into a separate method to reduce code duplication and improve maintainability. pyopenms_viz/_matplotlib/core.py [78-102] -self.fig.set_xlabel( - self.xlabel, - fontsize=9, - labelpad=-2, - color=ColorGenerator.color_blind_friendly_map[ - ColorGenerator.Colors.DARKGRAY - ], - style="italic", -) -self.fig.set_ylabel( - self.ylabel, - fontsize=9, - labelpad=-2, - color=ColorGenerator.color_blind_friendly_map[ - ColorGenerator.Colors.DARKGRAY - ], -) -self.fig.set_zlabel( - self.zlabel, - fontsize=10, - color=ColorGenerator.color_blind_friendly_map[ - ColorGenerator.Colors.DARKGRAY - ], - labelpad=-2, -) +def set_axis_label(self, axis, label, fontsize, labelpad, style=None): + kwargs = { + 'fontsize': fontsize, + 'labelpad': labelpad, + 'color': ColorGenerator.color_blind_friendly_map[ColorGenerator.Colors.DARKGRAY], + } + if style: + kwargs['style'] = style + getattr(self.fig, f'set_{axis}label')(label, **kwargs) +self.set_axis_label('x', self.xlabel, 9, -2, style='italic') +self.set_axis_label('y', self.ylabel, 9, -2) +self.set_axis_label('z', self.zlabel, 10, -2) + Apply this suggestion Suggestion importance[1-10]: 8 Why: This suggestion effectively reduces code duplication and enhances maintainability by consolidating repeated logic into a single method, which is a significant improvement.	8
	Use a more descriptive variable name for better code readability Consider using a more descriptive variable name instead of superFig to improve code readability. For example, main_figure or parent_figure would be more clear. pyopenms_viz/_matplotlib/core.py [61-63] -self.superFig, self.fig = plt.subplots( +self.main_figure, self.fig = plt.subplots( figsize=(self.width / 100, self.height / 100), dpi=100 ) Apply this suggestion Suggestion importance[1-10]: 6 Why: The suggestion to use a more descriptive variable name like main_figure instead of superFig improves code readability and maintainability, but it is not crucial for functionality.	6
	Use a more descriptive name for the show_default method Consider using a more descriptive name for the show_default method to better reflect its functionality, such as show_interactive_plot. pyopenms_viz/_matplotlib/core.py [220-223] -def show_default(self): +def show_interactive_plot(self): """ - Show the plot. + Show the interactive plot. """ Apply this suggestion Suggestion importance[1-10]: 5 Why: Renaming the method to better reflect its functionality can improve code clarity, but it is not a critical change and has limited impact on the overall codebase.	5
Best practice	Use a constant for the grid color to improve maintainability Consider using a constant for the color '#FF0000' to improve maintainability and make it easier to change the color in the future. pyopenms_viz/_matplotlib/core.py [118] -self.fig.grid(color="#FF0000", linewidth=0.8) +GRID_COLOR = "#FF0000" +self.fig.grid(color=GRID_COLOR, linewidth=0.8) Apply this suggestion Suggestion importance[1-10]: 7 Why: Using a constant for the grid color improves maintainability by making it easier to change the color in the future, though it is a minor enhancement.	7

💡 Need additional feedback ? start a PR chat