From 91ca8dcea4f41a52394068f61d77495289c4961d Mon Sep 17 00:00:00 2001 From: "Andre F. Rendeiro" Date: Sat, 19 Oct 2024 19:53:55 +0200 Subject: [PATCH] add docs --- .readthedocs.yaml | 12 ++++++++++ README.md | 4 ++++ docs/Makefile | 24 +++++++++++++++++++ docs/source/api.rst | 35 +++++++++++++++++++++++++++ docs/source/conf.py | 52 +++++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 42 +++++++++++++++++++++++++++++++++ docs/source/install.rst | 21 +++++++++++++++++ 7 files changed, 190 insertions(+) create mode 100644 .readthedocs.yaml create mode 100644 docs/Makefile create mode 100644 docs/source/api.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/install.rst diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..04526b2 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,12 @@ +# .readthedocs.yaml +version: 2 +sphinx: + configuration: docs/source/conf.py +build: + os: ubuntu-22.04 + tools: + python: "3.10" +python: + install: + - method: pip + path: . diff --git a/README.md b/README.md index a7c447f..3e32eba 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,9 @@ WSI ==== + +[![Documentation Status](https://readthedocs.org/projects/wsi/badge/?version=stable&style=flat-square)](https://wsi.readthedocs.io/en/stable) + + This is a fork of the repository from [Mahmood lab's CLAM repository](https://github.com/mahmoodlab/CLAM). It is made available under the GPLv3 License and is available for non-commercial academic purposes. diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..1732342 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,24 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +clean: + rm -rf "$(BUILDDIR)" + rm -rf $(SOURCEDIR)/api/_autogen/* + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/source/api.rst b/docs/source/api.rst new file mode 100644 index 0000000..e885b73 --- /dev/null +++ b/docs/source/api.rst @@ -0,0 +1,35 @@ +API reference +--------------- + +.. currentmodule:: wsi + +.. autoclass:: WholeSlideImage + + .. automethod:: __init__ + + .. rubric:: Methods + + .. autosummary:: + + ~WholeSlideImage.__init__ + ~WholeSlideImage.get_thumbnail + ~WholeSlideImage.segment + ~WholeSlideImage.plot_segmentation + ~WholeSlideImage.save_segmentation + ~WholeSlideImage.load_segmentation + ~WholeSlideImage.tile + ~WholeSlideImage.plot_tile_graph + ~WholeSlideImage.save_tile_images + ~WholeSlideImage.has_tile_coords + ~WholeSlideImage.has_tile_images + ~WholeSlideImage.has_tissue_contours + ~WholeSlideImage.get_tile_coordinate_level_size + ~WholeSlideImage.get_tile_coordinates + ~WholeSlideImage.get_tile_graph + ~WholeSlideImage.get_tile_images + ~WholeSlideImage.get_tile_polygons + ~WholeSlideImage.get_tile_tissue_piece + ~WholeSlideImage.inference + ~WholeSlideImage.as_tile_bag + ~WholeSlideImage.as_data_loader + ~WholeSlideImage.as_torch_geometric_data diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..a7fb0bc --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,52 @@ +from datetime import datetime + +import wsi + +project = "wsi" +copyright = f"{datetime.now().year}, Rendeiro Lab" +author = "wsi contributors" +release = wsi.__version__ + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "numpydoc", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.autosectionlabel", + "matplotlib.sphinxext.plot_directive", + "sphinx.ext.intersphinx", + "sphinx_design", + "sphinx_copybutton", + "sphinx_click", + "myst_nb", +] +autoclass_content = "class" +autodoc_docstring_signature = True +autodoc_default_options = {"members": None, "undoc-members": None} +autodoc_typehints = "none" +# setting autosummary +autosummary_generate = True +numpydoc_show_class_members = False +add_module_names = False + +templates_path = ["_templates"] +exclude_patterns = [] + + +html_theme = "pydata_sphinx_theme" +html_sidebars = {"installation": [], "api": []} +copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5," r"8}: " +copybutton_prompt_is_regexp = True + +# Plot directive +plot_include_source = True +plot_html_show_source_link = False +plot_html_show_formats = False +plot_formats = [("png", 200)] + +intersphinx_mapping = { + "torch": ("https://pytorch.org/docs/stable/", None), + "torch_geometric": ("https://pytorch-geometric.readthedocs.io/en/stable/", None), +} diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..4b4201f --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,42 @@ +wsi +=== + +**wsi** is a Python library for processing whole slide images (WSI). + +It is a simple library with an object-oriented interface where all operations are performed with a WholeSlideImage object. +It has the goal of doing basic processing of WSIs with reasonable defaults, but high customizability. +For example, to go from a slide remotely hosted to a torch geometric graph with ResNet50 features, the following lines suffice: + +.. code-block:: python + + from wsi import WholeSlideImage + slide = WholeSlideImage("https://brd.nci.nih.gov/brd/imagedownload/GTEX-O5YU-1426") + slide.segment() + slide.tile() + data = slide.as_torch_geometric_data(model_name='resnet50') + +Head over to the `Installation `_ and `API reference `_ pages to learn more. + + +.. toctree:: + :maxdepth: 1 + :hidden: + + install + api + + +.. grid:: 1 2 2 2 + :gutter: 2 + + .. grid-item-card:: Installation + :link: install + :link-type: doc + + Instructions for installation + + .. grid-item-card:: API + :link: api + :link-type: doc + + API documentation diff --git a/docs/source/install.rst b/docs/source/install.rst new file mode 100644 index 0000000..481e4a9 --- /dev/null +++ b/docs/source/install.rst @@ -0,0 +1,21 @@ +Installation +============ + +To install the package from the GitHub repository, follow the steps below. + +1. Ensure you have Python 3.10 or higher installed. +2. Install the package using `pip` by running the following command: + +.. code-block:: bash + + pip install git+https://github.com/rendeirolab/wsi.git + +3. Verify that the package is correctly installed by importing it in Python: + +.. code-block:: python + + import wsi + +If the installation was successful, you should not encounter any errors. + +For further details, please visit our `GitHub repository `_.