From 5396314aab0329e2261e2d62e4f6e4461cbe6d7e Mon Sep 17 00:00:00 2001 From: emdann Date: Tue, 25 Apr 2023 02:33:45 +0000 Subject: [PATCH] Automated template update from cookiecutter-scverse --- .cruft.json | 4 +- .flake8 | 57 ---- .github/ISSUE_TEMPLATE/bug_report.yml | 4 +- .gitignore.rej | 15 ++ .pre-commit-config.yaml.rej | 81 ++++++ README.md | 2 +- docs/_templates/autosummary/class.rst | 6 - docs/conf.py | 5 +- docs/contributing.md | 197 ++++++++++++++ docs/developer_docs.md | 371 -------------------------- docs/extensions/typed_returns.py | 17 +- docs/index.md | 3 +- docs/template_usage.md | 364 +++++++++++++++++++++++++ pyproject.toml | 80 ++++-- pyproject.toml.rej | 9 + 15 files changed, 740 insertions(+), 475 deletions(-) delete mode 100644 .flake8 create mode 100644 .gitignore.rej create mode 100644 .pre-commit-config.yaml.rej create mode 100644 docs/contributing.md delete mode 100644 docs/developer_docs.md create mode 100644 docs/template_usage.md create mode 100644 pyproject.toml.rej diff --git a/.cruft.json b/.cruft.json index cf0455b..25dc3ee 100644 --- a/.cruft.json +++ b/.cruft.json @@ -1,7 +1,7 @@ { "template": "https://github.com/scverse/cookiecutter-scverse", - "commit": "c96cadaa981a71113cc97ada8e5085188ed22ed7", - "checkout": "v0.1.1", + "commit": "57f6267716826dad73baba46dc3c00fe7262c459", + "checkout": "v0.2.0", "context": { "cookiecutter": { "project_name": "multi-view-atlas", diff --git a/.flake8 b/.flake8 deleted file mode 100644 index 10cfc5a..0000000 --- a/.flake8 +++ /dev/null @@ -1,57 +0,0 @@ -# Can't yet be moved to the pyproject.toml due to https://github.com/PyCQA/flake8/issues/234 -[flake8] -max-line-length = 120 -ignore = - # line break before a binary operator -> black does not adhere to PEP8 - W503 - # line break occured after a binary operator -> black does not adhere to PEP8 - W504 - # line too long -> we accept long comment lines; black gets rid of long code lines - 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 - # 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 - E741 - # Missing docstring in public package - D104 - # Missing docstring in public module - D100 - # Missing docstring in __init__ - D107 - # Errors from function calls in argument defaults. These are fine when the result is immutable. - B008 - # Missing docstring in magic method - D105 - # 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, diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 9dfd4ac..8d3ddaa 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -8,8 +8,8 @@ body: **Note**: Please read [this guide](https://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports) detailing how to provide the necessary information for us to reproduce your bug. In brief: * Please provide exact steps how to reproduce the bug in a clean Python environment. - * In case it's not clear what's causing this bug, please provide the data or the data generation procecure. - * Sometimes it is not possible to share the data but usually it is possible to replicate problems on publicly + * In case it's not clear what's causing this bug, please provide the data or the data generation procedure. + * Sometimes it is not possible to share the data, but usually it is possible to replicate problems on publicly available datasets or to share a subset of your data. - type: textarea diff --git a/.gitignore.rej b/.gitignore.rej new file mode 100644 index 0000000..f9e6e20 --- /dev/null +++ b/.gitignore.rej @@ -0,0 +1,15 @@ +diff a/.gitignore b/.gitignore (rejected hunks) +@@ -1,9 +1,13 @@ + # Temp files + .DS_Store + *~ ++buck-out/ + + # Compiled files ++.venv/ + __pycache__/ ++.mypy_cache/ ++.ruff_cache/ + + # Distribution / packaging + /build/ diff --git a/.pre-commit-config.yaml.rej b/.pre-commit-config.yaml.rej new file mode 100644 index 0000000..0e0f6f7 --- /dev/null +++ b/.pre-commit-config.yaml.rej @@ -0,0 +1,81 @@ +diff a/.pre-commit-config.yaml b/.pre-commit-config.yaml (rejected hunks) +@@ -7,32 +7,28 @@ default_stages: + minimum_pre_commit_version: 2.16.0 + repos: + - repo: https://github.com/psf/black +- rev: 23.3.0 ++ rev: "23.3.0" + hooks: + - id: black +- - repo: https://github.com/pre-commit/mirrors-prettier +- rev: v3.0.0-alpha.9-for-vscode +- hooks: +- - id: prettier + - repo: https://github.com/asottile/blacken-docs + rev: 1.13.0 + hooks: + - id: blacken-docs +- - repo: https://github.com/PyCQA/isort +- rev: 5.12.0 +- hooks: +- - id: isort +- - repo: https://github.com/asottile/yesqa +- rev: v1.4.0 ++ - repo: https://github.com/pre-commit/mirrors-prettier ++ rev: v3.0.0-alpha.9-for-vscode + hooks: +- - id: yesqa +- additional_dependencies: +- - flake8-tidy-imports +- - flake8-docstrings +- - flake8-rst-docstrings +- - flake8-comprehensions +- - flake8-bugbear +- - flake8-blind-except ++ - id: prettier ++ # Newer versions of node don't work on systems that have an older version of GLIBC ++ # (in particular Ubuntu 18.04 and Centos 7) ++ # EOL of Centos 7 is in 2024-06, we can probably get rid of this then. ++ # See https://github.com/scverse/cookiecutter-scverse/issues/143 and ++ # https://github.com/jupyterlab/jupyterlab/issues/12675 ++ language_version: "17.9.1" ++ - repo: https://github.com/charliermarsh/ruff-pre-commit ++ rev: v0.0.262 ++ hooks: ++ - id: ruff ++ args: [--fix, --exit-non-zero-on-fix] + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.4.0 + hooks: +@@ -43,31 +39,6 @@ repos: + args: [--fix=lf] + - id: trailing-whitespace + - id: check-case-conflict +- - repo: https://github.com/myint/autoflake +- rev: v2.1.1 +- hooks: +- - id: autoflake +- args: +- - --in-place +- - --remove-all-unused-imports +- - --remove-unused-variable +- - --ignore-init-module-imports +- - repo: https://github.com/PyCQA/flake8 +- rev: 6.0.0 +- hooks: +- - id: flake8 +- additional_dependencies: +- - flake8-tidy-imports +- - flake8-docstrings +- - flake8-rst-docstrings +- - flake8-comprehensions +- - flake8-bugbear +- - flake8-blind-except +- - repo: https://github.com/asottile/pyupgrade +- rev: v3.3.2 +- hooks: +- - id: pyupgrade +- args: [--py3-plus, --py38-plus, --keep-runtime-typing] + - repo: local + hooks: + - id: forbid-to-commit diff --git a/README.md b/README.md index c54976d..eb1a1f8 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![Tests][badge-tests]][link-tests] [![Documentation][badge-docs]][link-docs] -[badge-tests]: https://img.shields.io/github/workflow/status/emdann/multi-view-atlas/Test/main +[badge-tests]: https://img.shields.io/github/actions/workflow/status/emdann/multi-view-atlas/test.yaml?branch=main [link-tests]: https://github.com/emdann/multi-view-atlas/actions/workflows/test.yml [badge-docs]: https://img.shields.io/readthedocs/multi-view-atlas diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst index 17dc123..e4665df 100644 --- a/docs/_templates/autosummary/class.rst +++ b/docs/_templates/autosummary/class.rst @@ -39,9 +39,6 @@ Attributes {% for item in attributes %} -{{ item }} -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. autoattribute:: {{ [objname, item] | join(".") }} {%- endfor %} @@ -56,9 +53,6 @@ Methods {% for item in methods %} {%- if item != '__init__' %} -{{ item }} -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. automethod:: {{ [objname, item] | join(".") }} {%- endif -%} {%- endfor %} diff --git a/docs/conf.py b/docs/conf.py index fa02c9d..1ef4b56 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -65,7 +65,7 @@ napoleon_include_init_with_doc = False napoleon_use_rtype = True # having a separate entry generally helps readability napoleon_use_param = True -myst_heading_anchors = 3 # create anchors for h1-h3 +myst_heading_anchors = 6 # create anchors for h1-h6 myst_enable_extensions = [ "amsmath", "colon_fence", @@ -87,11 +87,11 @@ } intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), "anndata": ("https://anndata.readthedocs.io/en/stable/", None), "numpy": ("https://numpy.org/doc/stable/", None), } - # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. @@ -110,6 +110,7 @@ html_theme_options = { "repository_url": repository_url, "use_repository_button": True, + "path_to_docs": "docs/", } pygments_style = "default" diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..7fcc6ed --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,197 @@ +# Contributing guide + +Scanpy provides extensive [developer documentation][scanpy developer guide], most of which applies to this repo, too. +This document will not reproduce the entire content from there. Instead, it aims at summarizing the most important +information to get you started on contributing. + +We assume that you are already familiar with git and with making pull requests on GitHub. If not, please refer +to the [scanpy developer guide][]. + +## Installing dev dependencies + +In addition to the packages needed to _use_ this package, you need additional python packages to _run tests_ and _build +the documentation_. It's easy to install them using `pip`: + +```bash +cd multi-view-atlas +pip install -e ".[dev,test,doc]" +``` + +## Code-style + +This template uses [pre-commit][] to enforce consistent code-styles. On every commit, pre-commit checks will either +automatically fix issues with the code, or raise an error message. See [pre-commit checks](template_usage.md#pre-commit-checks) for +a full list of checks enabled for this repository. + +To enable pre-commit locally, simply run + +```bash +pre-commit install +``` + +in the root of the repository. Pre-commit will automatically download all dependencies when it is run for the first time. + +Alternatively, you can rely on the [pre-commit.ci][] service enabled on GitHub. If you didn't run `pre-commit` before +pushing changes to GitHub it will automatically commit fixes to your pull request, or show an error message. + +If pre-commit.ci added a commit on a branch you still have been working on locally, simply use + +```bash +git pull --rebase +``` + +to integrate the changes into yours. +While the [pre-commit.ci][] is useful, we strongly encourage installing and running pre-commit locally first to understand its usage. + +Finally, most editors have an _autoformat on save_ feature. Consider enabling this option for [black][black-editors] +and [prettier][prettier-editors]. + +[black-editors]: https://black.readthedocs.io/en/stable/integrations/editors.html +[prettier-editors]: https://prettier.io/docs/en/editors.html + +## Writing tests + +```{note} +Remember to first install the package with `pip install '-e[dev,test]'` +``` + +This package uses the [pytest][] for automated testing. Please [write tests][scanpy-test-docs] for every function added +to the package. + +Most IDEs integrate with pytest and provide a GUI to run tests. Alternatively, you can run all tests from the +command line by executing + +```bash +pytest +``` + +in the root of the repository. Continuous integration will automatically run the tests on all pull requests. + +[scanpy-test-docs]: https://scanpy.readthedocs.io/en/latest/dev/testing.html#writing-tests + +## Publishing a release + +### Updating the version number + +Before making a release, you need to update the version number. Please adhere to [Semantic Versioning][semver], in brief + +> Given a version number MAJOR.MINOR.PATCH, increment the: +> +> 1. MAJOR version when you make incompatible API changes, +> 2. MINOR version when you add functionality in a backwards compatible manner, and +> 3. PATCH version when you make backwards compatible bug fixes. +> +> Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format. + +We use [bump2version][] to automatically update the version number in all places and automatically create a git tag. +Run one of the following commands in the root of the repository + +```bash +bump2version patch +bump2version minor +bump2version major +``` + +Once you are done, run + +``` +git push --tags +``` + +to publish the created tag on GitHub. + +[bump2version]: https://github.com/c4urself/bump2version + +### Building and publishing the package on PyPI + +Python packages are not distributed as source code, but as _distributions_. The most common distribution format is the so-called _wheel_. To build a _wheel_, run + +```bash +python -m build +``` + +This command creates a _source archive_ and a _wheel_, which are required for publishing your package to [PyPI][]. These files are created directly in the root of the repository. + +Before uploading them to [PyPI][] you can check that your _distribution_ is valid by running: + +```bash +twine check dist/* +``` + +and finally publishing it with: + +```bash +twine upload dist/* +``` + +Provide your username and password when requested and then go check out your package on [PyPI][]! + +For more information, follow the [Python packaging tutorial][]. + +It is possible to automate this with GitHub actions, see also [this feature request][pypi-feature-request] +in the cookiecutter-scverse template. + +[python packaging tutorial]: https://packaging.python.org/en/latest/tutorials/packaging-projects/#generating-distribution-archives +[pypi-feature-request]: https://github.com/scverse/cookiecutter-scverse/issues/88 + +## Writing documentation + +Please write documentation for new or changed features and use-cases. This project uses [sphinx][] with the following features: + +- the [myst][] extension allows to write documentation in markdown/Markedly Structured Text +- [Numpy-style docstrings][numpydoc] (through the [napoloen][numpydoc-napoleon] extension). +- Jupyter notebooks as tutorials through [myst-nb][] (See [Tutorials with myst-nb](#tutorials-with-myst-nb-and-jupyter-notebooks)) +- [Sphinx autodoc typehints][], to automatically reference annotated input and output types + +See the [scanpy developer docs](https://scanpy.readthedocs.io/en/latest/dev/documentation.html) for more information +on how to write documentation. + +### Tutorials with myst-nb and jupyter notebooks + +The documentation is set-up to render jupyter notebooks stored in the `docs/notebooks` directory using [myst-nb][]. +Currently, only notebooks in `.ipynb` format are supported that will be included with both their input and output cells. +It is your reponsibility to update and re-run the notebook whenever necessary. + +If you are interested in automatically running notebooks as part of the continuous integration, please check +out [this feature request](https://github.com/scverse/cookiecutter-scverse/issues/40) in the `cookiecutter-scverse` +repository. + +#### Hints + +- If you refer to objects from other packages, please add an entry to `intersphinx_mapping` in `docs/conf.py`. Only + if you do so can sphinx automatically create a link to the external documentation. +- If building the documentation fails because of a missing link that is outside your control, you can add an entry to + the `nitpick_ignore` list in `docs/conf.py` + +#### Building the docs locally + +```bash +cd docs +make html +open _build/html/index.html +``` + + + +[scanpy developer guide]: https://scanpy.readthedocs.io/en/latest/dev/index.html +[cookiecutter-scverse-instance]: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/template_usage.html +[github quickstart guide]: https://docs.github.com/en/get-started/quickstart/create-a-repo?tool=webui +[codecov]: https://about.codecov.io/sign-up/ +[codecov docs]: https://docs.codecov.com/docs +[codecov bot]: https://docs.codecov.com/docs/team-bot +[codecov app]: https://github.com/apps/codecov +[pre-commit.ci]: https://pre-commit.ci/ +[readthedocs.org]: https://readthedocs.org/ +[myst-nb]: https://myst-nb.readthedocs.io/en/latest/ +[jupytext]: https://jupytext.readthedocs.io/en/latest/ +[pre-commit]: https://pre-commit.com/ +[anndata]: https://github.com/scverse/anndata +[mudata]: https://github.com/scverse/mudata +[pytest]: https://docs.pytest.org/ +[semver]: https://semver.org/ +[sphinx]: https://www.sphinx-doc.org/en/master/ +[myst]: https://myst-parser.readthedocs.io/en/latest/intro.html +[numpydoc-napoleon]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html +[numpydoc]: https://numpydoc.readthedocs.io/en/latest/format.html +[sphinx autodoc typehints]: https://github.com/tox-dev/sphinx-autodoc-typehints +[pypi]: https://pypi.org/ diff --git a/docs/developer_docs.md b/docs/developer_docs.md deleted file mode 100644 index 170109d..0000000 --- a/docs/developer_docs.md +++ /dev/null @@ -1,371 +0,0 @@ -# Developer documentation - -Welcome to the developer guidelines! This document is split into two parts: - -1. The [repository setup](#setting-up-the-repository). This section is relevant primarily for the repository maintainer and shows how to connect - continuous integration services and documents initial set-up of the repository. -2. The [contributor guide](#contributing-guide). It contains information relevant to all developers who want to make a contribution. - -## Setting up the repository - -### Documentation on _readthedocs_ - -We recommend using [readthedocs.org][] (RTD) to build and host the documentation for your project. -To enable readthedocs, head over to [their webiste][readthedocs.org] and sign in with your GitHub account. -On the RTD dashboard choose "Import a Project" and follow the instructions to add your repository. - -- Make sure to choose the correct name of the default branch. On GitHub, the default name of the default branch has - recently changed from `master` to `main`. -- We recommend to enable documentation builds for pull requests (PRs). This ensures that a PR doesn't introduce changes - that break the documentation. To do so, got to `Admin -> Advanced Settings`, check the - `Build pull requests for this projects` option, and click `Save`. For more information, please refer to - the [official RTD documentation](https://docs.readthedocs.io/en/stable/pull-requests.html). -- If you find the RTD builds are failing, you can disable the `fail_on_warning` option in `.readthedocs.yaml`. - -### Coverage tests with _Codecov_ - -Coverage tells what fraction of the code is "covered" by unit tests, thereby encouraging contributors to -[write tests](#writing-tests). -To enable coverage checks, head over to [codecov][] and sign in with your GitHub account. -You'll find more information in "getting started" section of the [codecov docs][]. - -In brief, you need to: - -1. Generate a Codecov Token by clicking _setup repo_ in the codecov dashboard. -2. Go to the _Settings_ of your newly created repository on GitHub. -3. Go to _Security > Secrets > Actions_. -4. Create new repository secret with name `CODECOV_TOKEN` and paste the token generated by codecov -5. Go back to Github Actions page an re-run previously failed jobs. - -### Pre-commit checks - -[Pre-commit][] checks are fast programs that -check code for errors, inconsistencies and code styles, before the code -is committed. - -We recommend setting up [pre-commit.ci][] to enforce consistency checks on every commit -and pull-request. - -To do so, head over to [pre-commit.ci][] and click "Sign In With GitHub". Follow -the instructions to enable pre-commit.ci for your account or your organization. You -may choose to enable the service for an entire organization or on a per-repository basis. - -Once authorized, pre-commit.ci should automatically be activated. - -#### Overview of pre-commit hooks used by the template - -The following pre-commit checks are for code style and format: - -- [black](https://black.readthedocs.io/en/stable/): standard code - formatter in Python. -- [isort](https://pycqa.github.io/isort/): sort module imports into - sections and types. -- [prettier](https://prettier.io/docs/en/index.html): standard code - formatter for non-Python files (e.g. YAML). -- [blacken-docs](https://github.com/asottile/blacken-docs): black on - python code in docs. - -The following pre-commit checks are for errors and inconsistencies: - -- [flake8](https://flake8.pycqa.org/en/latest/): standard check for errors in Python files. - - [flake8-tidy-imports](https://github.com/adamchainz/flake8-tidy-imports): - tidy module imports. - - [flake8-docstrings](https://github.com/PyCQA/flake8-docstrings): - pydocstyle extension of flake8. - - [flake8-rst-docstrings](https://github.com/peterjc/e8-rst-docstrings): - extension of `flake8-docstrings` for `rst` docs. - - [flake8-comprehensions](https://github.com/adamchainz/e8-comprehensions): - write better list/set/dict comprehensions. - - [flake8-bugbear](https://github.com/PyCQA/flake8-bugbear): - find possible bugs and design issues in program. - - [flake8-blind-except](https://github.com/elijahandrews/flake8-blind-except): - checks for blind, catch-all `except` statements. -- [yesqa](https://github.com/asottile/yesqa): - remove unneccesary `# noqa` comments, follows additional dependencies listed above. -- [autoflake](https://github.com/PyCQA/autoflake): - remove unused imports and variables. -- [pre-commit-hooks](https://github.com/pre-commit/pre-commit-hooks): generic pre-commit hooks. - - **detect-private-key**: checks for the existence of private keys. - - **check-ast**: check whether files parse as valid python. - - **end-of-file-fixer**:check files end in a newline and only a newline. - - **mixed-line-ending**: checks mixed line ending. - - **trailing-whitespace**: trims trailing whitespace. - - **check-case-conflict**: check files that would conflict with case-insensitive file systems. -- [pyupgrade](https://github.com/asottile/pyupgrade): - upgrade syntax for newer versions of the language. -- **forbid-to-commit**: Make sure that `*.rej` files cannot be commited. These files are created by the - [automated template sync](#automated-template-sync) if there's a merge conflict and need to be addressed manually. - -#### Notes on pre-commit checks - -- To ignore lint warnigs from **flake8**, see [Ignore certain lint warnings](#ignore-certain-lint-warnings). -- You can add or remove pre-commit checks by simply deleting relevant lines in the `.pre-commit-config.yaml` file. - Some pre-commit checks have additional options that can be specified either in the `pyproject.toml` or tool-specific - config files, such as `.prettierrc.yml` for **prettier** and `.flake8` for **flake8**. - -### API design - -Scverse ecosystem packages should operate on [AnnData][] and/or [MuData][] datastructures and typically use an API -as originally [introduced by scanpy][scanpy-api] with the following submodules: - -- `pp` for preprocessing -- `tl` for tools (that, compared to `pp` generate interpretable output, often associated with a corresponding plotting - function) -- `pl` for plotting functions - -You may add additional submodules as appropriate. While we encourage to follow a scanpy-like API for ecosystem packages, -there may also be good reasons to choose a different approach, e.g. using an object-oriented API. - -[scanpy-api]: https://scanpy.readthedocs.io/en/stable/usage-principles.html - -### Ignore certain lint warnings - -The [pre-commit checks](#pre-commit-checks) include [flake8](https://flake8.pycqa.org/en/latest/) which checks -for errors in Python files, including stylistic errors. - -In some cases it might overshoot and you may have good reasons to ignore certain warnings. - -To ignore an specific error on a per-case basis, you can add a comment `# noqa` to the offending line. You can also -specify the error ID to ignore, with e.g. `# noqa: E731`. Check the [flake8 guide][] for reference. - -Alternatively, you can disable certain error messages for the entire project. To do so, edit the `.flake8` -file in the root of the repository. Add one line per linting code you wish to ignore and don't forget to add a comment. - -```toml -... -# line break before a binary operator -> black does not adhere to PEP8 -W503 -# line break occured after a binary operator -> black does not adhere to PEP8 -W504 -... -``` - -[flake8 guide]: https://flake8.pycqa.org/en/3.1.1/user/ignoring-errors.html - -### Using VCS-based versioning - -By default, the template uses hard-coded version numbers that are set in `pyproject.toml` and [managed with -bump2version](#making-a-release). If you prefer to have your project automatically infer version numbers from git -tags, it is straightforward to switch to vcs-based versioning using [hatch-vcs][]. - -In `pyproject.toml` add the following changes, and you are good to go! - -```diff ---- a/pyproject.toml -+++ b/pyproject.toml -@@ -1,11 +1,11 @@ - [build-system] - build-backend = "hatchling.build" --requires = ["hatchling"] -+requires = ["hatchling", "hatch-vcs"] - - - [project] - name = "multi-view-atlas" --version = "0.3.1dev" -+dynamic = ["version"] - -@@ -60,6 +60,9 @@ -+[tool.hatch.version] -+source = "vcs" -+ - [tool.coverage.run] - source = ["multi-view-atlas"] - omit = [ -``` - -Don't forget to update the [Making a release section](#making-a-release) in this document accordingly, after you are done! - -[hatch-vcs]: https://pypi.org/project/hatch-vcs/ - -## Contributing guide - -Scanpy provides extensive [developer documentation][scanpy developer guide], most of which applies to this repo, too. -This document will not reproduce the entire content from there. Instead, it aims at summarizing the most important -information to get you started on contributing. - -We assume that you are already familiar with git and with making pull requests on GitHub. If not, please refer -to the [scanpy developer guide][]. - -### Installing dev dependencies - -In addition to the packages needed to _use_ this package, you need additional python packages to _run tests_ and _build -the documentation_. It's easy to install them using `pip`: - -```bash -cd multi-view-atlas -pip install -e ".[dev,test,doc]" -``` - -### Code-style - -This template uses [pre-commit][] to enforce consistent code-styles. On every commit, pre-commit checks will either -automatically fix issues with the code, or raise an error message. See [pre-commit checks](#pre-commit-checks) for -a full list of checks enabled for this repository. - -To enable pre-commit locally, simply run - -```bash -pre-commit install -``` - -in the root of the repository. Pre-commit will automatically download all dependencies when it is run for the first time. - -Alternatively, you can rely on the [pre-commit.ci][] service enabled on GitHub. If you didn't run `pre-commit` before -pushing changes to GitHub it will automatically commit fixes to your pull request, or show an error message. - -If pre-commit.ci added a commit on a branch you still have been working on locally, simply use - -```bash -git pull --rebase -``` - -to integrate the changes into yours. - -Finally, most editors have an _autoformat on save_ feature. Consider enabling this option for [black][black-editors] -and [prettier][prettier-editors]. - -[black-editors]: https://black.readthedocs.io/en/stable/integrations/editors.html -[prettier-editors]: https://prettier.io/docs/en/editors.html - -### Writing tests - -This package uses the [pytest][] for automated testing. Please [write tests][scanpy-test-docs] for every function added -to the package. - -Most IDEs integrate with pytest and provide a GUI to run tests. Alternatively, you can run all tests from the -command line by executing - -```bash -pytest -``` - -in the root of the repository. Continuous integration will automatically run the tests on all pull requests. - -[scanpy-test-docs]: https://scanpy.readthedocs.io/en/latest/dev/testing.html#writing-tests - -### Automated template sync - -Automated template sync is enabled by default. This means that every night, a GitHub action runs [cruft][] to check -if a new version of the `scverse-cookiecutter` template got released. If there are any new changes, a pull request -proposing these changes is created automatically. This helps keeping the repository up-to-date with the latest -coding standards. - -It may happen that a template sync results in a merge conflict. If this is the case a `*.ref` file with the -diff is created. You need to manually address these changes and remove the `.rej` file when you are done. -The pull request can only be merged after all `*.rej` files have been removed. - -:::{tip} -The following hints may be useful to work with the template sync: - -- GitHub automatically disables scheduled actions if there has been not activity to the repository for 60 days. - You can re-enable or manually trigger the sync by navigating to `Actions` -> `Sync Template` in your GitHub repository. -- If you want to ignore certain files from the template update, you can add them to the `[tool.cruft]` section in the - `pyproject.toml` file in the root of your repository. More details are described in the - [cruft documentation][cruft-update-project]. -- To disable the sync entirely, simply remove the file `.github/workflows/sync.yaml`. - -::: - -[cruft]: https://cruft.github.io/cruft/ -[cruft-update-project]: https://cruft.github.io/cruft/#updating-a-project - -### Making a release - -#### Updating the version number - -Before making a release, you need to update the version number. Please adhere to [Semantic Versioning][semver], in brief - -> Given a version number MAJOR.MINOR.PATCH, increment the: -> -> 1. MAJOR version when you make incompatible API changes, -> 2. MINOR version when you add functionality in a backwards compatible manner, and -> 3. PATCH version when you make backwards compatible bug fixes. -> -> Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format. - -We use [bump2version][] to automatically update the version number in all places and automatically create a git tag. -Run one of the following commands in the root of the repository - -```bash -bump2version patch -bump2version minor -bump2version major -``` - -Once you are done, run - -``` -git push --tags -``` - -to publish the created tag on GitHub. - -[bump2version]: https://github.com/c4urself/bump2version - -#### Upload on PyPI - -Please follow the [Python packaging tutorial][]. - -It is possible to automate this with GitHub actions, see also [this feature request][pypi-feature-request] -in the cookiecutter-scverse template. - -[python packaging tutorial]: https://packaging.python.org/en/latest/tutorials/packaging-projects/#generating-distribution-archives -[pypi-feature-request]: https://github.com/scverse/cookiecutter-scverse/issues/88 - -### Writing documentation - -Please write documentation for your package. This project uses [sphinx][] with the following features: - -- the [myst][] extension allows to write documentation in markdown/Markedly Structured Text -- [Numpy-style docstrings][numpydoc] (through the [napoloen][numpydoc-napoleon] extension). -- Jupyter notebooks as tutorials through [myst-nb][] (See [Tutorials with myst-nb](#tutorials-with-myst-nb-and-jupyter-notebooks)) -- [Sphinx autodoc typehints][], to automatically reference annotated input and output types - -See the [scanpy developer docs](https://scanpy.readthedocs.io/en/latest/dev/documentation.html) for more information -on how to write documentation. - -### Tutorials with myst-nb and jupyter notebooks - -The documentation is set-up to render jupyter notebooks stored in the `docs/notebooks` directory using [myst-nb][]. -Currently, only notebooks in `.ipynb` format are supported that will be included with both their input and output cells. -It is your reponsibility to update and re-run the notebook whenever necessary. - -If you are interested in automatically running notebooks as part of the continuous integration, please check -out [this feature request](https://github.com/scverse/cookiecutter-scverse/issues/40) in the `cookiecutter-scverse` -repository. - -#### Hints - -- If you refer to objects from other packages, please add an entry to `intersphinx_mapping` in `docs/conf.py`. Only - if you do so can sphinx automatically create a link to the external documentation. -- If building the documentation fails because of a missing link that is outside your control, you can add an entry to - the `nitpick_ignore` list in `docs/conf.py` - -#### Building the docs locally - -```bash -cd docs -make html -open _build/html/index.html -``` - - - -[scanpy developer guide]: https://scanpy.readthedocs.io/en/latest/dev/index.html -[codecov]: https://about.codecov.io/sign-up/ -[codecov docs]: https://docs.codecov.com/docs -[pre-commit.ci]: https://pre-commit.ci/ -[readthedocs.org]: https://readthedocs.org/ -[myst-nb]: https://myst-nb.readthedocs.io/en/latest/ -[jupytext]: https://jupytext.readthedocs.io/en/latest/ -[pre-commit]: https://pre-commit.com/ -[anndata]: https://github.com/scverse/anndata -[mudata]: https://github.com/scverse/mudata -[pytest]: https://docs.pytest.org/ -[semver]: https://semver.org/ -[sphinx]: https://www.sphinx-doc.org/en/master/ -[myst]: https://myst-parser.readthedocs.io/en/latest/intro.html -[numpydoc-napoleon]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html -[numpydoc]: https://numpydoc.readthedocs.io/en/latest/format.html -[sphinx autodoc typehints]: https://github.com/tox-dev/sphinx-autodoc-typehints diff --git a/docs/extensions/typed_returns.py b/docs/extensions/typed_returns.py index 9447813..1135204 100644 --- a/docs/extensions/typed_returns.py +++ b/docs/extensions/typed_returns.py @@ -1,24 +1,27 @@ # code from https://github.com/theislab/scanpy/blob/master/docs/extensions/typed_returns.py # with some minor adjustment +from __future__ import annotations + import re +from collections.abc import Generator, Iterable from sphinx.application import Sphinx from sphinx.ext.napoleon import NumpyDocstring -def _process_return(lines): +def _process_return(lines: Iterable[str]) -> Generator[str, None, None]: for line in lines: - m = re.fullmatch(r"(?P\w+)\s+:\s+(?P[\w.]+)", line) - if m: - # Once this is in scanpydoc, we can use the fancy hover stuff + if m := re.fullmatch(r"(?P\w+)\s+:\s+(?P[\w.]+)", line): yield f'-{m["param"]} (:class:`~{m["type"]}`)' else: yield line -def _parse_returns_section(self, section): - lines_raw = list(_process_return(self._dedent(self._consume_to_next_section()))) - lines = self._format_block(":returns: ", lines_raw) +def _parse_returns_section(self: NumpyDocstring, section: str) -> list[str]: + lines_raw = self._dedent(self._consume_to_next_section()) + if lines_raw[0] == ":": + del lines_raw[0] + lines = self._format_block(":returns: ", list(_process_return(lines_raw))) if lines and lines[-1]: lines.append("") return lines diff --git a/docs/index.md b/docs/index.md index 23a1e19..04d594a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,7 +8,8 @@ api.md changelog.md -developer_docs.md +template_usage.md +contributing.md references.md notebooks/example diff --git a/docs/template_usage.md b/docs/template_usage.md new file mode 100644 index 0000000..ae17161 --- /dev/null +++ b/docs/template_usage.md @@ -0,0 +1,364 @@ +# Using this template + +Welcome to the developer guidelines! This document is split into two parts: + +1. The [repository setup](#setting-up-the-repository). This section is relevant primarily for the repository maintainer and shows how to connect + continuous integration services and documents initial set-up of the repository. +2. The [contributor guide](contributing.md#contributing-guide). It contains information relevant to all developers who want to make a contribution. + +## Setting up the repository + +### First commit + +If you are reading this, you should have just completed the repository creation with : + +```bash +cruft create https://github.com/scverse/cookiecutter-scverse +``` + +and you should have + +``` +cd multi-view-atlas +``` + +into the new project directory. Now that you have created a new repository locally, the first step is to push it to github. To do this, you'd have to create a **new repository** on github. +You can follow the instructions directly on [github quickstart guide][]. +Since `cruft` already populated the local repository of your project with all the necessary files, we suggest to _NOT_ initialize the repository with a `README.md` file or `.gitignore`, because you might encounter git conflicts on your first push. +If you are familiar with git and knows how to handle git conflicts, you can go ahead with your preferred choice. + +:::{note} +If you are looking at this document in the [cookiecutter-scverse-instance][] repository documentation, throughout this document the name of the project is `cookiecutter-scverse-instance`. Otherwise it should be replaced by your new project name: `multi-view-atlas`. +::: + +Now that your new project repository has been created on github at `https://github.com/emdann/multi-view-atlas` you can push your first commit to github. +To do this, simply follow the instructions on your github repository page or a more verbose walkthrough here: + +Assuming you are in `/your/path/to/multi-view-atlas`. Add all files and commit. + +```bash +# stage all files of your new repo +git add --all +# commit +git commit -m "first commit" +``` + +You'll notice that the command `git commit` installed a bunch of packages and triggered their execution: those are pre-commit! To read more about what they are and what they do, you can go to the related section [Pre-commit checks](#pre-commit-checks) in this document. + +:::{note} +There is a chance that `git commit -m "first commit"` fails due to the `prettier` pre-commit formatting the file `.cruft.json`. No problem, you have just experienced what pre-commit checks do in action. Just go ahead and re-add the modified file and try to commit again: + +```bash + git add -u # update all tracked file + git commit -m "first commit" +``` + +::: + +Now that all the files of the newly created project have been committed, go ahead with the remaining steps: + +```bash +# update the `origin` of your local repo with the remote github link +git remote add origin https://github.com/emdann/multi-view-atlas.git +# rename the default branch to main +git branch -M main +# push all your files to remote +git push -u origin main +``` + +Your project should be now available at `https://github.com/emdann/multi-view-atlas`. While the repository at this point can be directly used, there are few remaining steps that needs to be done in order to achieve full functionality. + +### Coverage tests with _Codecov_ + +Coverage tells what fraction of the code is "covered" by unit tests, thereby encouraging contributors to +[write tests](contributing.md#writing-tests). +To enable coverage checks, head over to [codecov][] and sign in with your GitHub account. +You'll find more information in "getting started" section of the [codecov docs][]. + +In the `Actions` tab of your projects' github repository, you can see that the workflows are failing due to the **Upload coverage** step. The error message in the workflow should display something like: + +``` +... + Retrying 5/5 in 2s.. + {'detail': ErrorDetail(string='Could not find a repository, try using repo upload token', code='not_found')} +Error: 404 Client Error: Not Found for url: +... +``` + +While [codecov docs][] has a very extensive documentation on how to get started, _if_ you are using the default settings of this template we can assume that you are using [codecov][] in a github action workflow and hence you can make use of the [codecov bot][]. + +To set it up, simply go to the [codecov app][] page and follow the instructions to activate it for your repository. +Once the activation is completed, go back to the `Actions` tab and re-run the failing workflows. + +The workflows should now succeed and you will be able to find the code coverage at this link: `https://app.codecov.io/gh/emdann/multi-view-atlas`. You might have to wait couple of minutes and the coverage of this repository should be ~60%. + +If your repository is private, you will have to specify an additional token in the repository secrets. In brief, you need to: + +1. Generate a Codecov Token by clicking _setup repo_ in the codecov dashboard. + - If you have already set up codecov in the repository by following the previous steps, you can directly go to the codecov repo webpage. +2. Go to _Settings_ and copy **only** the token `_______-____-...`. +3. Go to _Settings_ of your newly created repository on GitHub. +4. Go to _Security > Secrets > Actions_. +5. Create new repository secret with name `CODECOV_TOKEN` and paste the token generated by codecov. +6. Past these additional lines in `/.github/workflows.test.yaml` under the **Upload coverage** step: + ```bash + - name: Upload coverage + uses: codecov/codecov-action@v3 + with: + token: ${{ secrets.CODECOV_TOKEN }} + ``` +7. Go back to github `Actions` page an re-run previously failed jobs. + +### Documentation on _readthedocs_ + +We recommend using [readthedocs.org][] (RTD) to build and host the documentation for your project. +To enable readthedocs, head over to [their website][readthedocs.org] and sign in with your GitHub account. +On the RTD dashboard choose "Import a Project" and follow the instructions to add your repository. + +- Make sure to choose the correct name of the default branch. On GitHub, the name of the default branch should be `main` (it has + recently changed from `master` to `main`). +- We recommend to enable documentation builds for pull requests (PRs). This ensures that a PR doesn't introduce changes + that break the documentation. To do so, got to `Admin -> Advanced Settings`, check the + `Build pull requests for this projects` option, and click `Save`. For more information, please refer to + the [official RTD documentation](https://docs.readthedocs.io/en/stable/pull-requests.html). +- If you find the RTD builds are failing, you can disable the `fail_on_warning` option in `.readthedocs.yaml`. + +If your project is private, there are ways to enable docs rendering on [readthedocs.org][] but it is more cumbersome and requires a different subscription for read the docs. See a guide [here](https://docs.readthedocs.io/en/stable/guides/importing-private-repositories.html). + +### Pre-commit checks + +[Pre-commit][] checks are fast programs that +check code for errors, inconsistencies and code styles, before the code +is committed. + +This template uses a number of pre-commit checks. In this section we'll detail what is used, where they're defined, and how to modify these checks. + +#### Pre-commit CI + +We recommend setting up [pre-commit.ci][] to enforce consistency checks on every commit +and pull-request. + +To do so, head over to [pre-commit.ci][] and click "Sign In With GitHub". Follow +the instructions to enable pre-commit.ci for your account or your organization. You +may choose to enable the service for an entire organization or on a per-repository basis. + +Once authorized, pre-commit.ci should automatically be activated. + +#### Overview of pre-commit hooks used by the template + +The following pre-commit hooks are for code style and format: + +- [black](https://black.readthedocs.io/en/stable/): + standard code formatter in Python. +- [blacken-docs](https://github.com/asottile/blacken-docs): + black on Python code in docs. +- [prettier](https://prettier.io/docs/en/index.html): + standard code formatter for non-Python files (e.g. YAML). +- [ruff][] based checks: + - [isort](https://beta.ruff.rs/docs/rules/#isort-i) (rule category: `I`): + sort module imports into sections and types. + - [pydocstyle](https://beta.ruff.rs/docs/rules/#pydocstyle-d) (rule category: `D`): + pydocstyle extension of flake8. + - [flake8-tidy-imports](https://beta.ruff.rs/docs/rules/#flake8-tidy-imports-tid) (rule category: `TID`): + tidy module imports. + - [flake8-comprehensions](https://beta.ruff.rs/docs/rules/#flake8-comprehensions-c4) (rule category: `C4`): + write better list/set/dict comprehensions. + - [pyupgrade](https://beta.ruff.rs/docs/rules/#pyupgrade-up) (rule category: `UP`): + upgrade syntax for newer versions of the language. + +The following pre-commit hooks are for errors and inconsistencies: + +- [pre-commit-hooks](https://github.com/pre-commit/pre-commit-hooks): generic pre-commit hooks for text files. + - **detect-private-key**: checks for the existence of private keys. + - **check-ast**: check whether files parse as valid python. + - **end-of-file-fixer**: check files end in a newline and only a newline. + - **mixed-line-ending**: checks mixed line ending. + - **trailing-whitespace**: trims trailing whitespace. + - **check-case-conflict**: check files that would conflict with case-insensitive file systems. + - **forbid-to-commit**: Make sure that `*.rej` files cannot be commited. + These files are created by the [automated template sync](#automated-template-sync) + if there's a merge conflict and need to be addressed manually. +- [ruff][] based checks: + - [pyflakes](https://beta.ruff.rs/docs/rules/#pyflakes-f) (rule category: `F`): + various checks for errors. + - [pycodestyle](https://beta.ruff.rs/docs/rules/#pycodestyle-e-w) (rule category: `E`, `W`): + various checks for errors. + - [flake8-bugbear](https://beta.ruff.rs/docs/rules/#flake8-bugbear-b) (rule category: `B`): + find possible bugs and design issues in program. + - [flake8-blind-except](https://beta.ruff.rs/docs/rules/#flake8-blind-except-ble) (rule category: `BLE`): + checks for blind, catch-all `except` statements. + - [Ruff-specific rules](https://beta.ruff.rs/docs/rules/#ruff-specific-rules-ruf) (rule category: `RUF`): + - `RUF100`: remove unneccesary `# noqa` comments () + +#### How to add or remove pre-commit checks + +The [pre-commit checks](#pre-commit-checks) check for both correctness and stylistic errors. +In some cases it might overshoot and you may have good reasons to ignore certain warnings. +This section shows you where these checks are defined, and how to enable/ disable them. + +##### pre-commit + +You can add or remove pre-commit checks by simply deleting relevant lines in the `.pre-commit-config.yaml` file under the repository root. +Some pre-commit checks have additional options that can be specified either in the `pyproject.toml` (for `ruff` and `black`) or tool-specific +config files, such as `.prettierrc.yml` for **prettier**. + +##### Ruff + +This template configures `ruff` through the `[tool.ruff]` entry in the `pyproject.toml`. +For further information `ruff` configuration, see [the docs](https://beta.ruff.rs/docs/configuration/). + +Ruff assigns code to the rules it checks (e.g. `E401`) and groups them under a rule category (e.g. `E`). +Rule categories are selectively enabled by including them under the `select` key: + +```toml +[tool.ruff] +... + +select = [ + "F", # Errors detected by Pyflakes + "E", # Error detected by Pycodestyle + "W", # Warning detected by Pycodestyle + "I", # isort + ... +] +``` + +The `ignore` entry is used to disable specific rules for the entire project. +Add the rule code(s) you want to ignore and don't forget to add a comment explaining why. +You can find a long list of checks that this template disables by default sitting there already. + +```toml +ignore = [ + ... + # __magic__ methods are are often self-explanatory, allow missing docstrings + "D105", + ... +] +``` + +Checks can be ignored per-file (or glob pattern) with `[tool.ruff.per-file-ignores]`. + +```toml +[tool.ruff.per-file-ignores] +"docs/*" = ["I"] +"tests/*" = ["D"] +"*/__init__.py" = ["F401"] +``` + +To ignore a specific rule on a per-case basis, you can add a `# noqa: [, , …]` comment to the offending line. +Specify the rule code(s) to ignore, with e.g. `# noqa: E731`. Check the [Ruff guide][] for reference. + +```{note} +The `RUF100` check will remove rule codes that are no longer necessary from `noqa` comments. +If you want to add a code that comes from a tool other than Ruff, +add it to Ruff’s [`external = [...]`](https://beta.ruff.rs/docs/settings/#external) setting to prevent `RUF100` from removing it. +``` + +[ruff]: https://beta.ruff.rs/docs/ +[ruff guide]: https://beta.ruff.rs/docs/configuration/#suppressing-errors + +### API design + +Scverse ecosystem packages should operate on [AnnData][] and/or [MuData][] data structures and typically use an API +as originally [introduced by scanpy][scanpy-api] with the following submodules: + +- `pp` for preprocessing +- `tl` for tools (that, compared to `pp` generate interpretable output, often associated with a corresponding plotting + function) +- `pl` for plotting functions + +You may add additional submodules as appropriate. While we encourage to follow a scanpy-like API for ecosystem packages, +there may also be good reasons to choose a different approach, e.g. using an object-oriented API. + +[scanpy-api]: https://scanpy.readthedocs.io/en/stable/usage-principles.html + +### Using VCS-based versioning + +By default, the template uses hard-coded version numbers that are set in `pyproject.toml` and [managed with +bump2version](contributing.md#publishing-a-release). If you prefer to have your project automatically infer version numbers from git +tags, it is straightforward to switch to vcs-based versioning using [hatch-vcs][]. + +In `pyproject.toml` add the following changes, and you are good to go! + +```diff +--- a/pyproject.toml ++++ b/pyproject.toml +@@ -1,11 +1,11 @@ + [build-system] + build-backend = "hatchling.build" +-requires = ["hatchling"] ++requires = ["hatchling", "hatch-vcs"] + + + [project] + name = "multi-view-atlas" +-version = "0.3.1dev" ++dynamic = ["version"] + +@@ -60,6 +60,9 @@ ++[tool.hatch.version] ++source = "vcs" ++ + [tool.coverage.run] + source = ["multi-view-atlas"] + omit = [ +``` + +Don't forget to update the [Making a release section](contributing.md#publishing-a-release) in this document accordingly, after you are done! + +[hatch-vcs]: https://pypi.org/project/hatch-vcs/ + +### Automated template sync + +Automated template sync is enabled by default. This means that every night, a GitHub action runs [cruft][] to check +if a new version of the `scverse-cookiecutter` template got released. If there are any new changes, a pull request +proposing these changes is created automatically. This helps keeping the repository up-to-date with the latest +coding standards. + +It may happen that a template sync results in a merge conflict. If this is the case a `*.ref` file with the +diff is created. You need to manually address these changes and remove the `.rej` file when you are done. +The pull request can only be merged after all `*.rej` files have been removed. + +:::{tip} +The following hints may be useful to work with the template sync: + +- GitHub automatically disables scheduled actions if there has been not activity to the repository for 60 days. + You can re-enable or manually trigger the sync by navigating to `Actions` -> `Sync Template` in your GitHub repository. +- If you want to ignore certain files from the template update, you can add them to the `[tool.cruft]` section in the + `pyproject.toml` file in the root of your repository. More details are described in the + [cruft documentation][cruft-update-project]. +- To disable the sync entirely, simply remove the file `.github/workflows/sync.yaml`. + +::: + +[cruft]: https://cruft.github.io/cruft/ +[cruft-update-project]: https://cruft.github.io/cruft/#updating-a-project + +## Moving forward + +You have reached the end of this document. Congratulations! You have successfully set up your project and are ready to start. +For everything else related to documentation, code style, testing and publishing your project ot pypi, please refer to the [contributing docs](contributing.md#contributing-guide). + + + +[scanpy developer guide]: https://scanpy.readthedocs.io/en/latest/dev/index.html +[cookiecutter-scverse-instance]: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/template_usage.html +[github quickstart guide]: https://docs.github.com/en/get-started/quickstart/create-a-repo?tool=webui +[codecov]: https://about.codecov.io/sign-up/ +[codecov docs]: https://docs.codecov.com/docs +[codecov bot]: https://docs.codecov.com/docs/team-bot +[codecov app]: https://github.com/apps/codecov +[pre-commit.ci]: https://pre-commit.ci/ +[readthedocs.org]: https://readthedocs.org/ +[myst-nb]: https://myst-nb.readthedocs.io/en/latest/ +[jupytext]: https://jupytext.readthedocs.io/en/latest/ +[pre-commit]: https://pre-commit.com/ +[anndata]: https://github.com/scverse/anndata +[mudata]: https://github.com/scverse/mudata +[pytest]: https://docs.pytest.org/ +[semver]: https://semver.org/ +[sphinx]: https://www.sphinx-doc.org/en/master/ +[myst]: https://myst-parser.readthedocs.io/en/latest/intro.html +[numpydoc-napoleon]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html +[numpydoc]: https://numpydoc.readthedocs.io/en/latest/format.html +[sphinx autodoc typehints]: https://github.com/tox-dev/sphinx-autodoc-typehints diff --git a/pyproject.toml b/pyproject.toml index 95a990d..972782f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -33,11 +33,12 @@ dependencies = [ dev = [ # CLI for bumping the version number "bump2version", - "pre-commit" + "pre-commit", + "twine>=4.0.2" ] doc = [ "sphinx>=4", - "sphinx-book-theme>=0.3.3", + "sphinx-book-theme>=1.0.0", "myst-nb", "sphinxcontrib-bibtex>=1.0.0", "sphinx-autodoc-typehints", @@ -64,32 +65,59 @@ addopts = [ "--import-mode=importlib", # allow using test files with same name ] -[tool.isort] -include_trailing_comma = true -multi_line_output = 3 -profile = "black" -skip_glob = ["docs/*"] - [tool.black] line-length = 120 -target-version = ['py38'] -include = '\.pyi?$' -exclude = ''' -( - /( - \.eggs - | \.git - | \.hg - | \.mypy_cache - | \.tox - | \.venv - | _build - | buck-out - | build - | dist - )/ -) -''' +target-version = ["py38"] + +[tool.ruff] +src = ["src"] +line-length = 120 +target-version = "py38" +select = [ + "F", # Errors detected by Pyflakes + "E", # Error detected by Pycodestyle + "W", # Warning detected by Pycodestyle + "I", # isort + "D", # pydocstyle + "B", # flake8-bugbear + "TID", # flake8-tidy-imports + "C4", # flake8-comprehensions + "BLE", # flake8-blind-except + "UP", # pyupgrade + "RUF100", # Report unused noqa directives +] +ignore = [ + # line too long -> we accept long comment lines; black gets rid of long code lines + "E501", + # 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 + "E741", + # Missing docstring in public package + "D104", + # Missing docstring in public module + "D100", + # Missing docstring in __init__ + "D107", + # Errors from function calls in argument defaults. These are fine when the result is immutable. + "B008", + # __magic__ methods are are often self-explanatory, allow missing docstrings + "D105", + # 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", + ## Disable one in each pair of mutually incompatible rules + # We don’t want a blank line before a class docstring + "D203", + # We want docstrings to start immediately after the opening triple quote + "D213", +] + +[tool.ruff.per-file-ignores] +"docs/*" = ["I"] +"tests/*" = ["D"] +"*/__init__.py" = ["F401"] [tool.jupytext] formats = "ipynb,md" diff --git a/pyproject.toml.rej b/pyproject.toml.rej new file mode 100644 index 0000000..5f0501f --- /dev/null +++ b/pyproject.toml.rej @@ -0,0 +1,9 @@ +diff a/pyproject.toml b/pyproject.toml (rejected hunks) +@@ -2,7 +2,6 @@ + build-backend = "hatchling.build" + requires = ["hatchling"] + +- + [project] + name = "multi-view-atlas" + version = "0.0.1"