Fix links to examples/tutorials in docs (theislab#480)

* Fix links to example/tutorials

* Update linter

* Better Codecov upload

* Fix RTD yaml file, add `build-package` tox command

* Fix .readthedocs.yml

* Use HTTPS instead of SSH for submodules

* Use `recursive: true

* Update submodule

.github/workflows/lint.yml

@@ -0,0 +1,53 @@
+name: Lint
+
+on:
+  schedule:
+    - cron: 00 00 * * 1
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint ${{ matrix.lint-kind }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # TODO(michalk8): in the future, lint the docs
+        lint-kind: [code] # , docs]
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+
+      - name: Cache pre-commit
+        uses: actions/cache@v3
+        if: ${{ matrix.lint-kind == 'code' }}
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ env.pythonLocation }}-${{ hashFiles('**/.pre-commit-config.yaml') }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install tox
+
+      - name: Install PyEnchant
+        if: ${{ matrix.lint-kind == 'docs' }}
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install libenchant-2-dev
+          python -m pip install pyenchant
+
+      - name: Lint ${{ matrix.lint-kind }}
+        run: |
+          tox -e lint-${{ matrix.lint-kind }}

.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: Upload Python Package
+
+on:
+  push:
+    branches: [main]
+    tags: [v*]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install tox
+
+      - name: Build package
+        run: tox -e build-package
+
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.TWINE_API_KEY }}
+          skip_existing: true
+          verify_metadata: true
+          verbose: true

.github/workflows/test.yml

@@ -1,39 +1,18 @@
 name: Test
 
 on:
+  schedule:
+    - cron: 00 00 * * 1
   push:
     branches: [main]
   pull_request:
     branches: [main]
 
 concurrency:
-  group: ${{ github.head_ref || github.run_id }}
+  group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
-  lint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - name: Set up Python 3.9
-        uses: actions/setup-python@v2
-        with:
-          python-version: 3.9
-
-      - uses: actions/cache@v2
-        with:
-          path: ~/.cache/pre-commit
-          key: precommit-${{ env.pythonLocation }}-${{ hashFiles('**/.pre-commit-config.yaml') }}
-
-      - name: Install pip dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install tox
-
-      - name: Lint
-        run: |-
-          echo "LINTING DISABLED"
-
   test:
     runs-on: ${{ matrix.os }}
     strategy:
@@ -49,54 +28,20 @@ jobs:
           python-version: ${{ matrix.python }}
 
       - name: Install pip dependencies
+        # TODO(michalk8): remove tox-gh dependency, update tox.ini
         run: |
           python -m pip install --upgrade pip
-          pip install tox tox-gh-actions codecov
+          pip install tox tox-gh-actions
       - name: Test
         run: |
           tox -vv
-      - name: Upload coverage
-        env:
-          CODECOV_NAME: ${{ matrix.python }}-${{ matrix.os }}
-          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
-        run: |-
-          codecov --no-color --required --flags unittests
-
-  regenerate-notebooks:
-    needs: test
-    if: ${{ (github.event_name == 'push' && (github.ref == 'refs/heads/main')) }}
-    runs-on: ubuntu-latest
-    steps:
-      - name: Rebuild tutorials/examples
-        uses: peter-evans/repository-dispatch@v1
-        with:
-          token: ${{ secrets.NOTEBOOKS_ACCESS_TOKEN }}
-          repository: theislab/moscot_notebooks
-          event-type: rebuild
-          client-payload: '{"ref": "${{ github.ref }}", "sha": "${{ github.sha }}"}'
 
-  deploy:
-    # this will run when you have tagged a commit, starting with "v*"
-    # and requires that you have put your twine API key in your
-    # github secrets (see readme for details)
-    needs: [test, regenerate-notebooks]
-    runs-on: ubuntu-latest
-    if: contains(github.ref, 'tags')
-    steps:
-      - uses: actions/checkout@v2
-      - name: Set up Python
-        uses: actions/setup-python@v2
+      - name: Upload coverage
+        uses: codecov/codecov-action@v3
         with:
-          python-version: "3.x"
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -U setuptools setuptools_scm wheel twine build
-      - name: Build and publish
-        env:
-          TWINE_USERNAME: __token__
-          TWINE_PASSWORD: ${{ secrets.TWINE_API_KEY }}
-        run: |
-          git tag
-          python -m build .
-          twine upload dist/*
+          files: ./coverage.xml
+          flags: tests-${{ matrix.os }}-${{ matrix.python }}
+          name: unittests
+          env_vars: OS,PYTHON
+          fail_ci_if_error: false
+          verbose: true

.gitmodules

@@ -1,3 +1,3 @@
 [submodule "docs/notebooks"]
 	path = docs/notebooks
-	url = ssh://git@github.com/theislab/moscot_notebooks
+	url = https://github.com/theislab/moscot_notebooks

.readthedocs.yml

@@ -1,23 +1,21 @@
 version: 2
 
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
 sphinx:
   builder: html
-  configuration: docs/source/conf.py
+  configuration: docs/conf.py
   fail_on_warning: false
 
-formats:
-  - htmlzip
-
-build:
-  image: testing
-
 python:
-  version: 3.9
   install:
     - method: pip
       path: .
-      extra_requirements:
-        - docs
+      extra_requirements: [docs]
 
 submodules:
-  include: [docs/source/notebooks]
+  include: [docs/notebooks]
+  recursive: true

docs/conf.py

@@ -13,7 +13,6 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#
 import moscot
 
 sys.path.insert(0, str(Path(__file__).parent / "extensions"))
@@ -35,28 +34,27 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
     "sphinx.ext.mathjax",
-    "sphinx_autodoc_typehints",
     "sphinx.ext.intersphinx",
     "sphinx.ext.autosummary",
     "sphinxcontrib.bibtex",
-    "typed_returns",
     "sphinx_copybutton",
     "myst_nb",
     "nbsphinx",
-    # TODO(michalk8): fix the lexer
-    "IPython.sphinxext.ipython_console_highlighting",
     "sphinx_design",  # for cards
+    "typed_returns",
 ]
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
     "scipy": ("https://docs.scipy.org/doc/scipy/", None),
-    "matplotlib": ("https://matplotlib.org/stable/", None),
+    "pandas": ("https://pandas.pydata.org/docs/", None),
+    "networkx": ("https://networkx.org/documentation/stable/", None),
     "jax": ("https://jax.readthedocs.io/en/latest/", None),
     "ott": ("https://ott-jax.readthedocs.io/en/latest/", None),
-    "pandas": ("https://pandas.pydata.org/docs/", None),
+    "matplotlib": ("https://matplotlib.org/stable/", None),
     "anndata": ("https://anndata.readthedocs.io/en/latest/", None),
     "scanpy": ("https://scanpy.readthedocs.io/en/latest/", None),
+    "squidpy": ("https://squidpy.readthedocs.io/en/latest/", None),
 }
 master_doc = "index"
 pygments_style = "sphinx"
@@ -87,6 +85,7 @@
 # This pattern also affects html_static_path and html_extra_path.
 autosummary_generate = True
 autodoc_member_order = "bysource"
+autodoc_typehints = "description"
 typehints_fully_qualified = False
 napoleon_google_docstring = False
 napoleon_numpy_docstring = True
@@ -102,7 +101,6 @@
 spelling_warning = True
 spelling_word_list_filename = "spelling_wordlist.txt"
 spelling_add_pypi_package_names = True
-spelling_show_suggestions = True
 spelling_exclude_patterns = ["references.rst"]
 # see: https://pyenchant.github.io/pyenchant/api/enchant.tokenize.html
 spelling_filters = [
@@ -111,7 +109,7 @@
     "enchant.tokenize.MentionFilter",
 ]
 
-exclude_patterns = ["build", "**.ipynb_checkpoints"]
+exclude_patterns = ["build", "**.ipynb_checkpoints", "notebooks/README.rst", "notebooks/CONTRIBUTING.rst"]
 
 # -- Options for HTML output -------------------------------------------------
 

docs/contributing.rst

@@ -1,4 +1,3 @@
 Contributing
 ============
-
-Under construction. Pleae feel free to reach out!
+Under construction. Please feel free to reach out!

docs/index.rst

@@ -29,13 +29,13 @@ well as the publication introducing the model, which can be found in the corresp
     Find a detailed documentation of ``moscot``.
 
 .. card:: Examples
-    :link: examples
+    :link: notebooks/examples/index
     :link-type: doc
 
     Find brief and concise examples of certain functionalities of ``moscot``.
 
 .. card:: Tutorials
-    :link: tutorials
+    :link: notebooks/tutorials/index
     :link-type: doc
 
     Check out how to use ``moscot`` for data analysis.

pyproject.toml

@@ -72,7 +72,6 @@ dev = [
 ]
 docs = [
     "sphinx>=5.1.1",
-    "sphinx-autodoc-typehints>=1.10.3",
     "sphinx_copybutton>=0.5.0",
     "sphinxcontrib-bibtex>=2.3.0",
     "sphinxcontrib-spelling>=7.6.2",

src/moscot/_docs/_docs.py

@@ -373,21 +373,20 @@
 # References to examples and notebooks
 
 _ex_solve_quadratic = """\
-See :ref:`sphx_glr_auto_examples_solvers_ex_quad_problems_basic.py` for a basic example
-how to solve quadratic problems.
-See :ref:`sphx_glr_auto_examples_solvers_ex_quad_problems_advanced.py` for an advanced
-example how to solve quadratic problems.
+See :doc:`../../notebooks/examples/solvers/300_quad_problems_basic` for a basic example of how to solve quadratic
+problems.
+See :doc:`../../notebooks/examples/solvers/400_quad_problems_advanced` for an advanced example how to solve quadratic
+problems.
 """
 _ex_solve_linear = """\
-See :ref:`sphx_glr_auto_examples_solvers_ex_linear_problems_basic.py` for a basic example
-how to solve linear problems.
-See :ref:`sphx_glr_auto_examples_solvers_ex_linear_problems_advanced.py` for an advanced
-example how to solve linear problems.
+See  :doc:`../../notebooks/examples/solvers/100_linear_problems_basic` for a basic example of how to solve linear
+problems.
+See :doc:`../../notebooks/examples/solvers/200_linear_problems_advanced` for an advanced example of how to solve linear
+problems.
 """
 _ex_prepare = """\
-See :ref:`sphx_glr_auto_examples_problems_ex_different_policies.py` for an example how to
-use different policies. See :ref:`sphx_glr_auto_examples_problems_ex_passing_marginals.py`
-for an example how to pass marginals.
+See :doc:`../../notebooks/examples/problems/400_subset_policy` for an example of how to use different policies.
+See :doc:`../../notebooks/examples/problems/500_passing_marginals` for an example of how to pass marginals.
 """
 _data_set = """\
 data

src/moscot/_utils.py

@@ -128,7 +128,7 @@ def wrapper(*args, **kwargs):
             collections = [collection[[ix], :] for ix in range(collection.shape[0])]  # type: ignore
         else:
             step = collection.shape[0] // n_split  # type: ignore[union-attr]
-            ixs = [np.arange(i * step, min((i + 1) * step, collection.shape[0])) for i in range(n_split)]  # type: ignore  # noqa:501
+            ixs = [np.arange(i * step, min((i + 1) * step, collection.shape[0])) for i in range(n_split)]  # type: ignore  # noqa: 501
             ixs[-1] = np.append(ixs[-1], np.arange(ixs[-1][-1] + 1, collection.shape[0]))  # type: ignore
 
             collections = [collection[ix, :] for ix in filter(len, ixs)]  # type:ignore[call-overload]
@@ -204,10 +204,10 @@ def _np_apply_along_axis(func1d, axis: int, arr: ArrayLike) -> ArrayLike:
 
 
 @njit(**jit_kwargs)
-def np_mean(array: ArrayLike, axis: int) -> ArrayLike:  # noqa
+def np_mean(array: ArrayLike, axis: int) -> ArrayLike:  # noqa: D103
     return _np_apply_along_axis(np.mean, axis, array)
 
 
 @njit(**jit_kwargs)
-def np_std(array: ArrayLike, axis: int) -> ArrayLike:  # noqa
+def np_std(array: ArrayLike, axis: int) -> ArrayLike:  # noqa: D103
     return _np_apply_along_axis(np.std, axis, array)

src/moscot/backends/ott/_output.py

@@ -204,5 +204,5 @@ def rank(self) -> int:
         lin_output = self._output if self.is_linear else self._output.linear_state
         return len(lin_output.g) if isinstance(lin_output, OTTLRSinkhornOutput) else -1
 
-    def _ones(self, n: int) -> jnp.ndarray:
+    def _ones(self, n: int) -> ArrayLike:
         return jnp.ones((n,))