Merge pull request #6 from Genentech/read-the-docs

read the docs

Author: joshua-gould

.readthedocs.yaml

@@ -0,0 +1,31 @@
+version: 2
+
+sphinx:
+  configuration: docs/conf.py
+python:
+  install:
+    - requirements: requirements.docs.txt
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  jobs:
+    install:
+      - pip install -e ".[doc]"
+    post_checkout:
+      - git fetch --unshallow || true
+      # Download and uncompress the binary
+      # https://git-lfs.github.com/
+      - wget https://github.com/git-lfs/git-lfs/releases/download/v3.1.4/git-lfs-linux-amd64-v3.1.4.tar.gz
+      - tar xvfz git-lfs-linux-amd64-v3.1.4.tar.gz git-lfs
+      # Modify LFS config paths to point where git-lfs binary was downloaded
+      - git config filter.lfs.process "`pwd`/git-lfs filter-process"
+      - git config filter.lfs.smudge  "`pwd`/git-lfs smudge -- %f"
+      - git config filter.lfs.clean "`pwd`/git-lfs clean -- %f"
+      # Make LFS available in current repository
+      - ./git-lfs install
+      # Download content from remote
+      - ./git-lfs fetch
+      # Make local files to have the real content on them
+      - ./git-lfs checkout

docs/conf.py

@@ -11,15 +11,13 @@
 sys.path.insert(0, str(HERE.parent))
 import scallops  # noqa
 
-
 project = "scallops"
 copyright = "2026, Genentech"
-author = "scallops team"
+author = "SCALLOPS team"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 extensions = [
-    "myst_parser",  # allow md files
     "nbsphinx",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
@@ -35,35 +33,37 @@
 suppress_warnings = [
     "nbsphinx",
 ]
-autodoc_default_options = {"members": True, "member-order": "bysource"}
+autodoc_default_options = {"members": True}
 autodoc_typehints = "description"
 autosummary_generate = True
 todo_include_todos = False
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
-# intersphinx_mapping = dict(
-#     matplotlib=("https://matplotlib.org/stable/", None),
-#     numpy=("https://numpy.org/doc/stable/", None),
-#     pandas=("https://pandas.pydata.org/pandas-docs/stable/", None),
-#     pytest=("https://docs.pytest.org/en/latest/", None),
-#     python=("https://docs.python.org/3", None),
-#     scipy=("https://docs.scipy.org/doc/scipy/", None),
-#     seaborn=("https://seaborn.pydata.org/", None),
-#     skimage=("https://scikit-image.org/docs/stable/api/", None),
-#     sklearn=("https://scikit-learn.org/dev/", None),
-#     xarray=("https://docs.xarray.dev/", None),
-# )
+intersphinx_mapping = dict(
+    matplotlib=("https://matplotlib.org/stable/", None),
+    numpy=("https://numpy.org/doc/stable/", None),
+    pandas=("https://pandas.pydata.org/pandas-docs/stable/", None),
+    pytest=("https://docs.pytest.org/en/latest/", None),
+    python=("https://docs.python.org/3", None),
+    scipy=("https://docs.scipy.org/doc/scipy/", None),
+    seaborn=("https://seaborn.pydata.org/", None),
+    skimage=("https://scikit-image.org/docs/stable/api/", None),
+    sklearn=("https://scikit-learn.org/dev/", None),
+    xarray=("https://docs.xarray.dev/", None),
+)
 intersphinx_disabled_reftypes = ["*"]
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "sphinx_rtd_theme"
 html_static_path = ["_static"]
+
+
 # Add custom CSS files
-html_css_files = [
-    "css/custom.css",
-]
+# html_css_files = [
+#     "css/custom.css",
+# ]
 
 
 def skip_private_members(app, what, name, obj, skip, options):

docs/index.rst

@@ -88,5 +88,5 @@ complex biological systems data.
    example_commands
    workflows
    example_notebooks
-   api
    faq
+   api

docs/install.rst

@@ -2,7 +2,16 @@
 Installation
 ************
 
-.
+
+PyPI Release
+=========================
+Install SCALLOPS using your favorite environment manager::
+
+    pip install scallops
+
+
+Developer Instructions
+========================
 
 
 1. Clone the repository::
@@ -30,12 +39,3 @@ Installation
 
 .. _Mamba: https://mamba.readthedocs.io/en/latest/installation.html
 .. _Conda: https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html
-
-
-
-Coming Soon: PyPI Release
-=========================
-We are planning to upload SCALLOPS to **PyPI** soon . Once available, you will
-be able to install the package using::
-
-    pip install scallops

pyproject.toml

@@ -85,7 +85,7 @@ dask-ml = [
 cellpose = [
     "cellpose<4"
 ]
-ufish= [
+ufish = [
     "ufish"
 ]
 test = [
@@ -99,12 +99,11 @@ dev = [
 ]
 doc = [
     "ipython",
-    "myst_parser",
     "nbsphinx",
     "sphinx-copybutton",
     "sphinx",
     "sphinx_argparse",
-    "sphinx_rtd_theme"
+    "sphinx_rtd_theme",
 ]
 all = [
     "napari",

requirements.doc.txt

@@ -1,7 +1,6 @@
-ipython==9.6.0
-myst_parser==4.0.1
-nbsphinx==0.9.7
+ipython==9.9.0
+nbsphinx==0.9.8
 sphinx-copybutton==0.5.2
-sphinx==8.1.3
+sphinx==9.1.0
 sphinx_argparse==0.5.2
-sphinx_rtd_theme==3.0.2
+sphinx_rtd_theme==3.1.0