Modernize docs (#17)

Co-authored-by: Frankie Robertson <[email protected]>

Author: flying-sheep

.gitignore

@@ -1,6 +1,7 @@
 # Caches
 __pycache__/
 /*cache/
+/node_modules/
 
 # Build artifacts
 /dist/

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v4.5.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
@@ -13,15 +13,15 @@ repos:
       - id: no-commit-to-branch
         args: ["--branch=main"]
   - repo: https://github.com/psf/black
-    rev: "23.3.0"
+    rev: "23.12.0"
     hooks:
       - id: black
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: v0.0.275
+    rev: v0.1.7
     hooks:
       - id: ruff
         args: ["--fix"]
   - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v2.7.1
+    rev: v4.0.0-alpha.4
     hooks:
       - id: prettier

.readthedocs.yml renamed to .readthedocs.yaml

@@ -4,11 +4,14 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
-  jobs:
-    post_install:
-      - pip install poetry
-      - poetry config virtualenvs.create false
-      - poetry install --with=docs
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+        - annlibs
 
 sphinx:
   configuration: docs/conf.py

README.rst

@@ -35,17 +35,13 @@ perform competitively in high dimensional spaces.
 Development
 ===========
 
-This project is managed using Poetry_ and pre-commit_.
-To get started, run ``pre-commit install`` once and ``poetry install ...``
-whenever dependencies have changed. E.g. @flying-sheep runs::
-
-    poetry install --with=test --extras=annlibs
-
-This installs all optional (dev) dependencies except for those to build the docs.
-pre-commit_ comes into play on every `git commit` after installation.
+This project is managed using Hatch_ and pre-commit_. To get started, run ``pre-commit
+install`` and ``hatch env create``. Run all commands using ``hatch run python
+<command>`` which will ensure the environment is kept up to date. pre-commit_ comes into
+play on every `git commit` after installation.
 
 Consult ``pyproject.toml`` for which dependency groups and extras exist,
-and the poetry help or user guide for more info on what they are.
+and the Hatch help or user guide for more info on what they are.
 
-.. _poetry: https://python-poetry.org/
+.. _Hatch: https://hatch.pypa.io/
 .. _pre-commit: https://pre-commit.com/

docs/Makefile

@@ -4,9 +4,9 @@
 # You can set these variables from the command line, and also
 # from the environment for the first two.
 SPHINXOPTS    ?=
-SPHINXBUILD   ?= poetry run sphinx-build
-SOURCEDIR     = .
-BUILDDIR      = _build
+SPHINXBUILD   ?= hatch run sphinx-build
+SOURCEDIR     = $(CURDIR)
+BUILDDIR      = $(CURDIR)/_build
 
 # Put it first so that "make" without argument is like "make help".
 help:

docs/_templates/autosummary/class.rst

@@ -0,0 +1,33 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. add toctree option to make autodoc generate the pages
+
+.. autoclass:: {{ objname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Attributes
+
+   .. autosummary::
+      :toctree: .
+   {% for item in attributes %}
+      ~{{ fullname }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: Methods
+
+   .. autosummary::
+      :toctree: .
+   {% for item in methods %}
+      {%- if item != '__init__' %}
+      ~{{ fullname }}.{{ item }}
+      {%- endif -%}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/conf.py

@@ -4,18 +4,17 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+import os
+
 # -- Path setup --------------------------------------------------------------
 
 # 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 os
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
-import sphinx_rtd_theme
-
 # -- Project information -----------------------------------------------------
 
 project = "sklearn-ann"
@@ -31,9 +30,11 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
-    "numpydoc",
+    "sphinx.ext.napoleon",
+    "scanpydoc.definition_list_typed_field",
+    "scanpydoc.rtd_github_links",
     "sphinx_issues",
-    "sphinx.ext.viewcode",
+    "sphinx.ext.linkcode",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -45,19 +46,21 @@
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 autosummary_generate = True
+autodoc_default_options = {
+    "undoc-members": True,
+}
 
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ["_static"]
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_theme = "sphinx_book_theme"
+html_theme_options = dict(
+    repository_url="https://github.com/frankier/sklearn-ann",
+    repository_branch=os.environ.get("READTHEDOCS_GIT_IDENTIFIER", "main"),
+)
+rtd_links_prefix = "src"
 
 autodoc_mock_imports = ["annoy", "faiss", "pynndescent", "nmslib"]

pyproject.toml

@@ -19,12 +19,13 @@ tests = [
     "pytest-cov>=2.10.1",
 ]
 docs = [
-    "sphinx>=4.2.0",
+    "sphinx>=7",
     "sphinx-gallery>=0.8.2",
-    "sphinx-rtd-theme>=0.5.1",
+    "sphinx-book-theme>=1.1.0rc1",
     "sphinx-issues>=1.2.0",
     "numpydoc>=1.1.0",
-    "matplotlib>=3.3.3"
+    "matplotlib>=3.3.3",
+    "scanpydoc",
 ]
 annoy = [
     "annoy>=1.17.0,<2.0.0",
@@ -81,6 +82,7 @@ features = [
 
 [tool.hatch.envs.default.scripts]
 test = "pytest {args:tests}"
+build-docs = "sphinx-build -M html docs docs/_build"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/sklearn_ann"]