docs (#4)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.flake8

@@ -10,35 +10,48 @@ ignore =
     E501
     # whitespace before : -> black does not adhere to PEP8
     E203
+    # line break before binary operator -> black does not adhere to PEP8
+    W503
     # missing whitespace after ,', ';', or ':' -> black does not adhere to PEP8
     E231
     # continuation line over-indented for hanging indent -> black does not adhere to PEP8
     E126
-    # E266 too many leading '#' for block comment -> this is fine for indicating sections
+    # too many leading '#' for block comment -> this is fine for indicating sections
     E262
     # Do not assign a lambda expression, use a def -> lambda expression assignments are convenient
     E731
-    # allow I, O, l as variable names -> I is the identity matrix, i, j, k, l is reasonable indexing notation
+    # allow I, O, l as variable names -> I is the identity matrix
     E741
     # Missing docstring in public package
     D104
-    # ... imported but unused
-    F401
     # Missing docstring in public module
     D100
     # Missing docstring in __init__
     D107
-    # Do not perform function calls in argument defaults.
+    # Errors from function calls in argument defaults. These are fine when the result is immutable.
     B008
-    # line break before binary operator
-    W503
     # Missing docstring in magic method
     D105
-    # whitespace before ':'
-    E203
     # format string does contain unindexed parameters
     P101
+    # first line should end with a period [Bug: doesn't work with single-line docstrings]
+    D400
+    # First line should be in imperative mood; try rephrasing
+    D401
 exclude = .git,__pycache__,build,docs/_build,dist
 per-file-ignores =
     tests/*: D
     */__init__.py: F401
+rst-roles =
+    class,
+    func,
+    ref,
+    cite:p,
+    cite:t,
+rst-directives =
+    envvar,
+    exception,
+rst-substitutions =
+    version,
+extend-ignore =
+    RST307,

.github/workflows/test.yaml

@@ -16,7 +16,7 @@ jobs:
         strategy:
             fail-fast: false
             matrix:
-                python: ["3.8", "3.10"]
+                python: ["3.9", "3.10"]
                 os: [ubuntu-latest]
 
         env:

.gitignore

@@ -22,3 +22,7 @@ __pycache__/
 # IDEs
 /.idea/
 /.vscode/
+
+# docs
+/docs/generated/
+/docs/_build/

.mypy.ini

@@ -0,0 +1,28 @@
+[mypy]
+python_version = 3.9
+plugins = numpy.typing.mypy_plugin
+
+ignore_errors = False
+warn_redundant_casts = True
+warn_unused_configs = True
+warn_unused_ignores = True
+
+disallow_untyped_calls = False
+disallow_untyped_defs = True
+disallow_incomplete_defs = True
+disallow_any_generics = True
+
+strict_optional = True
+strict_equality = True
+warn_return_any = True
+warn_unreachable = False
+check_untyped_defs = True
+; because of docrep
+allow_untyped_decorators = True
+no_implicit_optional = True
+no_implicit_reexport = True
+no_warn_no_return = True
+
+show_error_codes = True
+show_column_numbers = True
+error_summary = True

.pre-commit-config.yaml

@@ -7,21 +7,27 @@ default_stages:
 minimum_pre_commit_version: 2.16.0
 repos:
     - repo: https://github.com/psf/black
-      rev: 22.8.0
+      rev: 22.12.0
       hooks:
           - id: black
     - repo: https://github.com/pre-commit/mirrors-prettier
-      rev: v3.0.0-alpha.0
+      rev: v3.0.0-alpha.4
       hooks:
           - id: prettier
     - repo: https://github.com/asottile/blacken-docs
       rev: v1.12.1
       hooks:
           - id: blacken-docs
     - repo: https://github.com/PyCQA/isort
-      rev: 5.10.1
+      rev: v5.11.3
       hooks:
           - id: isort
+    - repo: https://github.com/pre-commit/mirrors-mypy
+      rev: v0.991
+      hooks:
+          - id: mypy
+            additional_dependencies: [numpy==1.23.0]
+            exclude: tests/|docs/|src/spatialdata_io/xenium.py|src/spatialdata_io/visium.py|src/spatialdata_io/resolve.py|
     - repo: https://github.com/asottile/yesqa
       rev: v1.4.0
       hooks:
@@ -34,7 +40,7 @@ repos:
                 - flake8-bugbear
                 - flake8-blind-except
     - repo: https://github.com/pre-commit/pre-commit-hooks
-      rev: v4.3.0
+      rev: v4.4.0
       hooks:
           - id: detect-private-key
           - id: check-ast
@@ -44,7 +50,7 @@ repos:
           - id: trailing-whitespace
           - id: check-case-conflict
     - repo: https://github.com/myint/autoflake
-      rev: v1.6.1
+      rev: v2.0.0
       hooks:
           - id: autoflake
             args:
@@ -53,7 +59,7 @@ repos:
                 - --remove-unused-variable
                 - --ignore-init-module-imports
     - repo: https://github.com/PyCQA/flake8
-      rev: 5.0.4
+      rev: 6.0.0
       hooks:
           - id: flake8
             additional_dependencies:
@@ -64,7 +70,20 @@ repos:
                 - flake8-bugbear
                 - flake8-blind-except
     - repo: https://github.com/asottile/pyupgrade
-      rev: v2.38.2
+      rev: v3.3.1
       hooks:
           - id: pyupgrade
-            args: [--py3-plus, --py38-plus, --keep-runtime-typing]
+            args: [--py3-plus, --py39-plus, --keep-runtime-typing]
+    - repo: local
+      hooks:
+          - id: forbid-to-commit
+            name: Don't commit rej files
+            entry: |
+                Cannot commit .rej files. These indicate merge conflicts that arise during automated template updates.
+                Fix the merge conflicts manually and remove the .rej files.
+            language: fail
+            files: '.*\.rej$'
+    - repo: https://github.com/PyCQA/doc8
+      rev: v1.0.0
+      hooks:
+          - id: doc8

docs/Makefile

@@ -18,3 +18,7 @@ help:
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+clean:
+	rm -r "$(BUILDDIR)"
+	rm -r "generated"

docs/_templates/autosummary/class.rst

@@ -0,0 +1,75 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. add toctree option to make autodoc generate the pages
+
+.. autoclass:: {{ objname }}
+
+{% block attributes %}
+{% if attributes %}
+Attributes table
+~~~~~~~~~~~~~~~~~~
+
+.. autosummary::
+
+{% for item in attributes %}
+
+    ~{{ fullname }}.{{ item }}
+
+{%- endfor %}
+{% endif %}
+{% endblock %}
+
+{% block methods %}
+{% if methods %}
+Methods table
+~~~~~~~~~~~~~
+
+.. autosummary::
+
+{% for item in methods %}
+
+    {%- if item != '__init__' %}
+    ~{{ fullname }}.{{ item }}
+    {%- endif -%}
+
+{%- endfor %}
+{% endif %}
+{% endblock %}
+
+{% block attributes_documentation %}
+{% if attributes %}
+Attributes
+~~~~~~~~~~~
+
+{% for item in attributes %}
+
+{{ item }}
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autoattribute:: {{ [objname, item] | join(".") }}
+
+{%- endfor %}
+
+{% endif %}
+{% endblock %}
+
+{% block methods_documentation %}
+{% if methods %}
+Methods
+~~~~~~~
+
+{% for item in methods %}
+{%- if item != '__init__' %}
+
+{{ item }}
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automethod:: {{ [objname, item] | join(".") }}
+
+{%- endif -%}
+{%- endfor %}
+
+{% endif %}
+{% endblock %}

docs/api.md

@@ -1,37 +1,7 @@
 # API
 
-## Preprocessing
+## Coming soon
 
 ```{eval-rst}
-.. module:: spatialdata_io.pp
-.. currentmodule:: spatialdata_io
 
-.. autosummary::
-    :toctree: generated
-
-    pp.basic_preproc
-```
-
-## Tools
-
-```{eval-rst}
-.. module:: spatialdata_io.tl
-.. currentmodule:: spatialdata_io
-
-.. autosummary::
-    :toctree: generated
-
-    tl.basic_tool
-```
-
-## Plotting
-
-```{eval-rst}
-.. module:: spatialdata_io.pl
-.. currentmodule:: spatialdata_io
-
-.. autosummary::
-    :toctree: generated
-
-    pl.basic_plot
 ```