[DE-7207] Fix sphinx doc build errors and warnings

[edwinpav]

Main change is I removed the deprecated pkg_resources package and replaced it withimportlib-metadata. pkg_resources package was causing 2 main problems:

1. Preventing the successful build of the new auto generated sdk docs (see here)
2. Whenever the SDK threw an error back to the user, they always got this pkg_resources is deprecated message, which was annoying, misleading, and confusing. They got this error because this package was imported in the errors.py file since one of the error messages is meant to remind the user of the version package that they're on, and to update it to the most recent version if applicable.

I also fixed the formatting of many pages/documentation.

When running sphinx-build -b html . _build/html before my changes, there were ~79 errors/warnings. Now, there is only 13 warnings and 0 errors.

For example, fixed this this entire page (if you go on it now, its super messy and clunky): https://docs.nucleus.scale.com/en/latest/api/nucleus/model_run/index.html#module-nucleus.model_run.ModelRun.predict

Other examples:
(old)

(new)

Greptile Summary

This PR replaces the deprecated pkg_resources package with importlib_metadata for version lookups, fixes ~66 Sphinx documentation build errors/warnings, and resolves circular import issues in the metrics subpackage.

• Replaced pkg_resources.get_distribution with importlib_metadata.version in docs/conf.py and nucleus/errors.py, eliminating deprecation warnings shown to users on SDK errors
• Added from . import metrics to nucleus/__init__.py for autoapi doc generation, and fixed resulting circular imports by changing metrics/custom_types.py and metrics/segmentation_utils.py to import directly from nucleus.annotation and nucleus.prediction instead of top-level nucleus
• Rewrote docstrings across model_run.py, __init__.py, validate/client.py, and validate/scenario_test_metric.py from ad-hoc :param/:return: format to Napoleon-style Parameters:/Returns:: with proper RST formatting
• Fixed RST template in docs/_templates/python/module.rst to use dynamic heading underline length
• Consolidated duplicate [tool.poetry.group.dev.dependencies] section and migrated from deprecated [tool.poetry.dev-dependencies] in pyproject.toml
• Removed deprecated pylint options (bad-continuation, no-self-use) from .pylintrc

Confidence Score: 4/5

• This PR is safe to merge — changes are primarily documentation formatting and a dependency swap with no behavioral changes to SDK logic.
• The core functional change (replacing pkg_resources with importlib_metadata) is straightforward and well-executed. The circular import fix in metrics subpackage is correctly handled. All other changes are docstring reformatting. The only minor consideration is the new importlib-metadata runtime dependency, but it's the correct choice given the Python >=3.7 support requirement.
• Pay attention to nucleus/__init__.py (new from . import metrics import) and nucleus/metrics/custom_types.py / nucleus/metrics/segmentation_utils.py (circular import fixes) to confirm no import regressions.

Important Files Changed

Filename	Overview
nucleus/init.py	Added from . import metrics, moved requests/tqdm imports above pydantic compatibility block, and reformatted docstrings for Sphinx compliance. Import reordering fixes circular import with metrics subpackage.
nucleus/errors.py	Replaced deprecated pkg_resources with importlib_metadata for getting package version in NucleusAPIError.
docs/conf.py	Replaced pkg_resources with importlib_metadata, removed deprecated html_theme_options for furo theme.
nucleus/metrics/custom_types.py	Changed imports from nucleus (top-level) to nucleus.annotation and nucleus.prediction directly, fixing circular import caused by new from . import metrics in __init__.py.
nucleus/metrics/segmentation_utils.py	Changed imports from nucleus to direct submodule imports (nucleus.annotation, nucleus.prediction) to avoid circular imports.
nucleus/metrics/init.py	Added module docstring and __all__ with Metric and ScalarResult to control autoapi doc generation.
nucleus/model_run.py	Rewrote all docstrings from ad-hoc :param/:return: format to proper Napoleon-style Parameters: and Returns:: with RST code blocks.
nucleus/validate/client.py	Fixed docstring indentation and Raises: format to proper Sphinx-compatible exception documentation.
pyproject.toml	Added importlib-metadata as runtime dependency, consolidated duplicate [tool.poetry.group.dev.dependencies] section, migrated from deprecated [tool.poetry.dev-dependencies].
docs/_templates/python/module.rst	Fixed RST heading underline to dynamically match module name length instead of fixed =============.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["nucleus/__init__.py"] -->|"from . import metrics (NEW)"| B["nucleus/metrics/__init__.py"]
    B --> C["nucleus/metrics/custom_types.py"]
    B --> D["nucleus/metrics/segmentation_utils.py"]
    C -->|"OLD: from nucleus import ..."| A
    C -->|"NEW: from nucleus.annotation import ..."| E["nucleus/annotation.py"]
    C -->|"NEW: from nucleus.prediction import ..."| F["nucleus/prediction.py"]
    D -->|"OLD: from nucleus import ..."| A
    D -->|"NEW: from nucleus.annotation import ..."| E
    D -->|"NEW: from nucleus.prediction import ..."| F
    A --> E
    A --> F

    style A fill:#e1f5fe
    style B fill:#e1f5fe
    style C fill:#fff3e0
    style D fill:#fff3e0
    style E fill:#e8f5e9
    style F fill:#e8f5e9

Loading

_{Last reviewed commit: c583cdd}

[edwinpav]

Main change

[greptile-apps]

_{16 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[edwinpav]

bad-continuation was deleted from pylint entirely in version 2.6

[edwinpav]

Using error code seems more robust than using optional no-self-use

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	jupyterlab@​3.5.3
	sphinx@​4.3.2
	virtualenv@​20.16.2
	nbconvert@​6.5.4
	nbformat@​5.6.0
	jupyterlab-server@​2.12.0
	lxml@​5.4.0
	platformdirs@​2.6.2
	importlib-metadata@​6.7.0 ⏵ 1.7.0
	importlib-metadata@​6.7.0 ⏵ 8.7.1	+1
	mistune@​0.8.4

View full report

[edwinpav]

Was getting:

The "poetry.dev-dependencies" section is deprecated and will be removed in a future version. Use "poetry.group.dev.dependencies" instead.

poetry.group.dev.dependencies already exited below, so I merged that into this, and changed the name of this section to the non-deprecated version.