Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: initialize Sphinx Gallery #2508

Merged
merged 28 commits into from
May 6, 2024
Merged
Show file tree
Hide file tree
Changes from 26 commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
ca17f2c
rename existing `examples/`
Borda Apr 18, 2024
be4925c
sphinx gallery init
Borda Apr 18, 2024
31f09ac
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Apr 18, 2024
03aefb2
linting
Borda Apr 18, 2024
00eced8
bash
Borda Apr 18, 2024
ceba923
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Apr 18, 2024
6eaabba
conf
Borda Apr 18, 2024
74db2c8
Merge branch 'docs/gallery' of https://github.com/PyTorchLightning/me…
Borda Apr 18, 2024
35d8b62
ignore
Borda Apr 18, 2024
1a73270
skimage
Borda Apr 18, 2024
7796fb0
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Apr 18, 2024
9c4b425
thumbnail
Borda Apr 18, 2024
fc07902
Merge branch 'docs/gallery' of https://github.com/PyTorchLightning/me…
Borda Apr 18, 2024
5d40d6e
notes
Borda Apr 19, 2024
73c8e72
(400, 280)
Borda Apr 19, 2024
418f7d7
Merge branch 'master' into docs/gallery
Borda Apr 20, 2024
e6de42e
Merge branch 'master' into docs/gallery
Borda Apr 24, 2024
098ffc8
Disable Gallery build
Borda Apr 29, 2024
646f91a
Merge branch 'master' into docs/gallery
Borda Apr 29, 2024
8068775
dummy file
Borda Apr 29, 2024
d9a63cf
Merge branch 'docs/gallery' of https://github.com/PyTorchLightning/me…
Borda Apr 29, 2024
434bf3a
makedirs
Borda Apr 30, 2024
ecac3b7
Merge branch 'master' into docs/gallery
Borda Apr 30, 2024
14777a6
Merge branch 'master' into docs/gallery
Borda Apr 30, 2024
510d06c
header
Borda Apr 30, 2024
529cfc9
_samples
Borda Apr 30, 2024
d0b709a
Merge branch 'master' into docs/gallery
mergify[bot] May 4, 2024
6a57e5a
Update requirements/_docs.txt
Borda May 4, 2024
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .azure/gpu-unittests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -219,7 +219,7 @@ jobs:
echo "Processing $fn example..."
python $fn
done
workingDirectory: "examples/"
workingDirectory: "_samples/"
# skip for PR if there is nothing to test, note that outside PR there is default 'unittests'
condition: and(succeeded(), ne(variables['TEST_DIRS'], ''))
displayName: "Examples"
Expand Down
3 changes: 3 additions & 0 deletions .github/workflows/docs-build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,9 @@ jobs:
- name: Full build for deployment
if: github.event_name != 'pull_request'
run: echo "SPHINX_FETCH_ASSETS=1" >> $GITHUB_ENV
- name: Disable Gallery build
if: matrix.target != 'html'
run: echo "SPHINX_ENABLE_GALLERY=0" >> $GITHUB_ENV
- name: make ${{ matrix.target }}
working-directory: ./docs
run: make ${{ matrix.target }} --debug --jobs $(nproc) SPHINXOPTS="-W --keep-going"
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@ coverage.xml
docs/_build/
docs/source/api/
docs/source/generated/
docs/source/gallery/
docs/source/*.md
docs/source/_static/fetched-s3-assets

Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -335,7 +335,7 @@ fig3, ax3 = acc.plot(values)
<img src="docs/source/_static/images/plot_example.png" width="1000">
</p>

For examples of plotting different metrics try running [this example file](examples/plotting.py).
For examples of plotting different metrics try running [this example file](_samples/plotting.py).

## Contribute!

Expand Down
File renamed without changes.
File renamed without changes.
File renamed without changes.
38 changes: 26 additions & 12 deletions docs/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@
SPHINX_MOCK_REQUIREMENTS = int(os.environ.get("SPHINX_MOCK_REQUIREMENTS", True))
SPHINX_FETCH_ASSETS = int(os.environ.get("SPHINX_FETCH_ASSETS", False))
SPHINX_PIN_RELEASE_VERSIONS = int(os.getenv("SPHINX_PIN_RELEASE_VERSIONS", False))
SPHINX_ENABLE_GALLERY = int(os.getenv("SPHINX_ENABLE_GALLERY", True))

html_favicon = "_static/images/icon.svg"

Expand Down Expand Up @@ -128,15 +129,22 @@ def _set_root_image_path(page_path: str) -> None:
"sphinx.ext.autosummary",
"sphinx.ext.napoleon",
"sphinx.ext.mathjax",
"myst_parser",
"sphinx.ext.autosectionlabel",
"nbsphinx",
"sphinx.ext.githubpages",
"sphinx_autodoc_typehints",
"sphinx_paramlinks",
"sphinx.ext.githubpages",
"lai_sphinx_theme.extensions.lightning",
"myst_parser",
"matplotlib.sphinxext.plot_directive",
"lai_sphinx_theme.extensions.lightning",
]
if SPHINX_ENABLE_GALLERY:
extensions.append("sphinx_gallery.gen_gallery")
else:
# write a dummy file as placeholder
path_gallery = os.path.join(_PATH_HERE, "gallery")
os.makedirs(path_gallery, exist_ok=True)
with open(os.path.join(path_gallery, "index.rst"), "w") as fopen:
fopen.write("Gallery is disabled\n===================")

# Set that source code from plotting is always included
plot_include_source = True
Expand All @@ -146,13 +154,19 @@ def _set_root_image_path(page_path: str) -> None:
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]

# https://berkeley-stat159-f17.github.io/stat159-f17/lectures/14-sphinx..html#conf.py-(cont.)
# https://stackoverflow.com/questions/38526888/embed-ipython-notebook-in-sphinx-document
# I execute the notebooks manually in advance. If notebooks test the code,
# they should be run at build time.
nbsphinx_execute = "never"
nbsphinx_allow_errors = True
nbsphinx_requirejs_path = ""
sphinx_gallery_conf = {
"examples_dirs": os.path.join(_PATH_ROOT, "examples"), # path to your example scripts
"gallery_dirs": "gallery", # path to where to save gallery generated output
"filename_pattern": ".",
"ignore_pattern": r"__init__\.py",
"example_extensions": {".py"},
"line_numbers": True,
"promote_jupyter_magic": True,
Borda marked this conversation as resolved.
Show resolved Hide resolved
"matplotlib_animations": True,
"abort_on_example_error": True,
# 'only_warn_on_example_error': True
"thumbnail_size": (400, 280),
}

myst_update_mathjax = False

Expand All @@ -162,7 +176,7 @@ def _set_root_image_path(page_path: str) -> None:
".rst": "restructuredtext",
".txt": "markdown",
".md": "markdown",
".ipynb": "nbsphinx",
# ".ipynb": "nbsphinx",
}

# The master toctree document.
Expand Down
1 change: 1 addition & 0 deletions docs/source/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,7 @@ Or directly from conda

pages/quickstart
all-metrics
gallery/index
pages/overview
pages/plotting
pages/implement
Expand Down
6 changes: 6 additions & 0 deletions examples/README.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
TorchMetrics' gallery
=====================

Welcome to a comprehensive guide on leveraging TorchMetrics, that facilitates the precise and consistent evaluation of machine learning models. As an integral tool for developers and researchers, TorchMetrics offers an array of metrics critical for assessing model performance across a variety of applications. Whether you are fine-tuning a neural network, comparing model iterations, or tracking performance improvements, this page provides a gallery of real-world applications where Torch Metrics can be effectively implemented.

By touring through this application gallery, users can gain insights into how TorchMetrics is utilized across different sectors and scale settings, empowering them with the knowledge to implement metrics effectively in their own projects. Whether your interest lies in academic research or commercial product development, the examples provided here will help demonstrate the versatility and utility of Torch Metrics in enhancing machine learning model assessment.
4 changes: 4 additions & 0 deletions examples/image/README.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
Image domain
============

Image-domain metrics are pivotal for gauging the performance of models in tasks like object detection, and segmentation. TorchMetrics provides a suite of specialized metrics designed for these purposes. Using these image-specific metrics from Torch Metrics helps in developing more precise and robust image-based models, ensuring that performance evaluations are both meaningful and directly applicable to practical vision tasks.
57 changes: 57 additions & 0 deletions examples/image/spatial_correlation_coef.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
"""
Spatial Correlation Coefficient
===============================

The Spatial Correlation Coefficient can be applied to compare the spatial structure of two images, which can be valuable in various domains such as medical imaging, remote sensing, and quality assessment in manufacturing or design processes.

Let's consider a use case in medical imaging where Spatial Correlation Coefficient is used to compare the spatial correlation between a reference image and a reconstructed medical scan.
This can be particularly relevant in evaluating the accuracy of image reconstruction techniques or assessing the quality of medical imaging data.
"""

# %%
# Here's a hypothetical Python example demonstrating the usage of the Spatial Correlation Coefficient to compare two medical images:

import matplotlib.pyplot as plt
import numpy as np
import torch
from skimage.data import shepp_logan_phantom
from skimage.transform import iradon, radon, rescale
from torchmetrics.image import SpatialCorrelationCoefficient

# %%
# Create a Shepp-Logan phantom image
phantom = shepp_logan_phantom()
phantom = rescale(phantom, scale=512 / 400) # Rescaling to 512x512

# %%
# Simulate projection data (sinogram) using Radon transform
theta = np.linspace(0.0, 180.0, max(phantom.shape), endpoint=False)
sinogram = radon(phantom, theta=theta)

# %%
# Perform reconstruction using the inverse Radon transform
reconstruction = iradon(sinogram, theta=theta, circle=True)

# %%
# Display the results
fig, (ax1, ax2, ax3) = plt.subplots(1, 3, figsize=(10, 4))
ax1.set_title("Original")
ax1.imshow(phantom, cmap=plt.cm.Greys_r)
ax2.set_title("Radon transform (Sinogram)")
ax2.imshow(sinogram, cmap=plt.cm.Greys_r, extent=(0, 180, 0, sinogram.shape[0]), aspect="equal")
ax3.set_title("Reconstruction from sinogram")
ax3.imshow(reconstruction, cmap=plt.cm.Greys_r)
fig.tight_layout()

# %%
# Convert the images to PyTorch tensors
phantom_tensor = torch.from_numpy(phantom).float().unsqueeze(0).unsqueeze(0)
reconstructed_tensor = torch.from_numpy(reconstruction).float().unsqueeze(0).unsqueeze(0)

# %%
# Calculating the Spatial Correlation Coefficient
scc = SpatialCorrelationCoefficient()
score = scc(preds=reconstructed_tensor, target=phantom_tensor)

print(f"Spatial Correlation Coefficient between the images: {score}")
fig.suptitle(f"Spatial Correlation Coefficient: {score:.5}", y=-0.01)
14 changes: 10 additions & 4 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -55,18 +55,24 @@ unfixable = ["F401"]
[tool.ruff.lint.per-file-ignores]
"setup.py" = ["ANN202", "ANN401"]
"docs/source/conf.py" = ["A001", "D103"]
"examples/*" = [
"E501", # Line too long (XXX > 120)
"D205", # 1 blank line required between summary line and description
"D212", # [*] Multi-line docstring summary should start at the first line
"D415", # First line should end with a period, question mark, or exclamation point
]
"src/**" = [
"ANN401",
"S310", # todo: Audit URL open for permitted schemes. Allowing use of `file:` or custom schemes is often unexpected. # todo
]
"S310", # todo: Audit URL open for permitted schemes. Allowing use of `file:` or custom schemes is often unexpected.
]
"tests/**" = [
"ANN001",
"ANN201",
"ANN202",
"ANN401",
"S101",
"S301", # todo: `pickle` and modules that wrap it can be unsafe when used to deserialize untrusted data, possible security issue # todo
]
"S301", # todo: `pickle` and modules that wrap it can be unsafe when used to deserialize untrusted data, possible security issue
]

[tool.ruff.lint.pydocstyle]
# Use Google-style docstrings.
Expand Down
9 changes: 7 additions & 2 deletions requirements/_docs.txt
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
sphinx ==5.3.0
myst-parser ==1.0.0
nbsphinx ==0.9.3
pandoc ==2.3
docutils ==0.19
sphinxcontrib-fulltoc >=1.0
Expand All @@ -10,6 +9,7 @@ sphinx-autodoc-typehints ==1.23.0
sphinx-paramlinks ==0.6.0
sphinx-togglebutton ==0.3.2
sphinx-copybutton ==0.5.2
sphinx-gallery ==0.15.0

lightning >=1.8.0, <2.3.0
lightning-utilities ==0.11.2
Expand All @@ -23,4 +23,9 @@ pydantic > 1.0.0, < 3.0.0
-r image.txt
-r multimodal.txt
-r text.txt
-r text_test.txt

# Gallery extra requirements
# --------------------------
# todo: until this hase reolution - https://github.com/sphinx-gallery/sphinx-gallery/issues/1290
Borda marked this conversation as resolved.
Show resolved Hide resolved
# Image
scikit-image ~=0.21
Loading