From 147bbbda5321dfb3694d6928a505af976509f7bb Mon Sep 17 00:00:00 2001 From: Philipp A Date: Wed, 13 Dec 2023 12:00:57 +0100 Subject: [PATCH] Modernize docs (#17) Co-authored-by: Frankie Robertson --- .gitignore | 1 + .pre-commit-config.yaml | 8 +++---- .readthedocs.yml => .readthedocs.yaml | 13 +++++++---- README.rst | 16 +++++-------- docs/Makefile | 6 ++--- docs/_templates/autosummary/class.rst | 33 +++++++++++++++++++++++++++ docs/conf.py | 27 ++++++++++++---------- pyproject.toml | 8 ++++--- 8 files changed, 75 insertions(+), 37 deletions(-) rename .readthedocs.yml => .readthedocs.yaml (59%) create mode 100644 docs/_templates/autosummary/class.rst diff --git a/.gitignore b/.gitignore index 13314b1..25ef0a7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ # Caches __pycache__/ /*cache/ +/node_modules/ # Build artifacts /dist/ diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index b5af159..13a5206 100644 --- a/.pre-commit-config.yaml +++ b/.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 diff --git a/.readthedocs.yml b/.readthedocs.yaml similarity index 59% rename from .readthedocs.yml rename to .readthedocs.yaml index 78203e6..5c36bc6 100644 --- a/.readthedocs.yml +++ b/.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 diff --git a/README.rst b/README.rst index 9082849..c058536 100644 --- a/README.rst +++ b/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 +`` 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/ diff --git a/docs/Makefile b/docs/Makefile index 672ce2e..d9157c7 100644 --- a/docs/Makefile +++ b/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: diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst new file mode 100644 index 0000000..b4e7370 --- /dev/null +++ b/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 %} diff --git a/docs/conf.py b/docs/conf.py index f0d285a..66b5a00 100644 --- a/docs/conf.py +++ b/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,6 +46,9 @@ exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] autosummary_generate = True +autodoc_default_options = { + "undoc-members": True, +} # -- Options for HTML output ------------------------------------------------- @@ -52,12 +56,11 @@ # 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"] diff --git a/pyproject.toml b/pyproject.toml index 954fe2d..529934b 100644 --- a/pyproject.toml +++ b/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"]