improve documentation build process by removing warnings

[sophiamaedler]

Summary

This PR reduces Sphinx warning noise and makes docs builds more reliable.

• Docs build tooling

  • docs/Makefile: switched to interpreter-based Sphinx invocation and improved make target handling.
  • docs/conf.py: suppressed known non-actionable config.cache warning.

• Docs warning cleanup

  • Fixed duplicate explicit target names and broken refs in:
    • docs/index.rst
    • docs/pages/workflow.rst
    • docs/pages/workflow/segmentation_workflow.rst
  • Added :no-index: to specific autodoc blocks causing duplicate object description warnings:
    • docs/pages/module/processing.rst
    • docs/pages/module/tools/ml.rst
  • Re-enabled notebook page in toctree to avoid orphan warnings (docs/index.rst).

• Dependency adjustments

  • Added ipython to docs requirements for notebook lexer support.
  • Added setuptools<81 to maintain current pkg_resources compatibility in dependency stack.

• Docstring formatting

  • Cleaned numpy_to_h5sc docstring formatting in src/scportrait/io/h5sc.py to avoid docutils option-list parsing warnings.

• Pre-commit mypy

  • Set mypy hook to --python-version=3.10 in .pre-commit-config.yaml to match project syntax/features.

[Copilot]

Pull request overview

This PR aims to reduce Sphinx warning noise and make documentation builds more reliable by adjusting the docs build tooling, suppressing a known warning, cleaning up broken/duplicate references, and tweaking dependency/tooling configs.

Changes:

• Updated Sphinx build invocation and configuration to reduce warning noise (docs/Makefile, docs/conf.py).
• Cleaned up documentation references / toctrees and suppressed duplicate autodoc indexing warnings (docs/**/*.rst).
• Adjusted dependencies and tooling configuration for docs and type checking (requirements/*.txt, .pre-commit-config.yaml).

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
docs/Makefile	Switches Sphinx invocation to interpreter-based module execution and improves target handling.
docs/conf.py	Suppresses the config.cache warning to reduce non-actionable noise.
docs/index.rst	Fixes/adjusts links and re-adds notebook page to toctree to avoid warnings.
docs/pages/workflow.rst	Improves link text and references within the workflow documentation.
docs/pages/workflow/segmentation_workflow.rst	Fixes a broken :ref: target for the DAPI cellpose section.
docs/pages/module/processing.rst	Adds :no-index: to reduce duplicate object description warnings from autodoc.
docs/pages/module/tools/ml.rst	Adds :no-index: to reduce duplicate object description warnings from autodoc.
src/scportrait/io/h5sc.py	Re-formats docstring sections to avoid docutils parsing warnings.
requirements/requirements_docs.txt	Adds ipython for notebook lexer support in docs builds.
requirements/requirements.txt	Adds a setuptools upper bound intended to preserve pkg_resources compatibility.
.pre-commit-config.yaml	Pins mypy’s target --python-version to 3.10 to match project support.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.