Skip to content

Commit

Permalink
Update instance repo from cookiecutter template
Browse files Browse the repository at this point in the history
  • Loading branch information
github-actions[bot] committed Oct 19, 2022
1 parent dc27d6d commit 3b6369e
Show file tree
Hide file tree
Showing 17 changed files with 315 additions and 27 deletions.
2 changes: 2 additions & 0 deletions .flake8
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,8 @@ rst-roles =
class,
func,
ref,
cite:p,
cite:t,
rst-directives =
envvar,
exception,
Expand Down
89 changes: 89 additions & 0 deletions .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
name: Bug report
description: Report something that is broken or incorrect
labels: bug
body:
- type: markdown
attributes:
value: |
**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
available datasets or to share a subset of your data.
- type: textarea
id: report
attributes:
label: Report
description: A clear and concise description of what the bug is.
validations:
required: true

- type: textarea
id: versions
attributes:
label: Version information
description: |
Please paste below the output of
```python
import session_info
session_info.show(html=False, dependencies=True)
```
placeholder: |
-----
anndata 0.8.0rc2.dev27+ge524389
session_info 1.0.0
-----
asttokens NA
awkward 1.8.0
backcall 0.2.0
cython_runtime NA
dateutil 2.8.2
debugpy 1.6.0
decorator 5.1.1
entrypoints 0.4
executing 0.8.3
h5py 3.7.0
ipykernel 6.15.0
jedi 0.18.1
mpl_toolkits NA
natsort 8.1.0
numpy 1.22.4
packaging 21.3
pandas 1.4.2
parso 0.8.3
pexpect 4.8.0
pickleshare 0.7.5
pkg_resources NA
prompt_toolkit 3.0.29
psutil 5.9.1
ptyprocess 0.7.0
pure_eval 0.2.2
pydev_ipython NA
pydevconsole NA
pydevd 2.8.0
pydevd_file_utils NA
pydevd_plugins NA
pydevd_tracing NA
pygments 2.12.0
pytz 2022.1
scipy 1.8.1
setuptools 62.5.0
setuptools_scm NA
six 1.16.0
stack_data 0.3.0
tornado 6.1
traitlets 5.3.0
wcwidth 0.2.5
zmq 23.1.0
-----
IPython 8.4.0
jupyter_client 7.3.4
jupyter_core 4.10.0
-----
Python 3.9.13 | packaged by conda-forge | (main, May 27 2022, 16:58:50) [GCC 10.3.0]
Linux-5.18.6-arch1-1-x86_64-with-glibc2.35
-----
Session information updated at 2022-07-07 17:55
5 changes: 5 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
blank_issues_enabled: false
contact_links:
- name: Scverse Community Forum
url: https://discourse.scverse.org/
about: If you have questions about “How to do X”, please ask them here.
11 changes: 11 additions & 0 deletions .github/ISSUE_TEMPLATE/feature_request.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
name: Feature request
description: Propose a new feature for cookiecutter-scverse-instance
labels: enhancement
body:
- type: textarea
id: description
attributes:
label: Description of feature
description: Please describe your suggestion for a new feature. It might help to describe a problem or use case, plus any alternatives that you have considered.
validations:
required: true
6 changes: 3 additions & 3 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ repos:
hooks:
- id: black
- repo: https://github.com/pre-commit/mirrors-prettier
rev: v3.0.0-alpha.1
rev: v3.0.0-alpha.2
hooks:
- id: prettier
- repo: https://github.com/asottile/blacken-docs
Expand Down Expand Up @@ -44,7 +44,7 @@ repos:
- id: trailing-whitespace
- id: check-case-conflict
- repo: https://github.com/myint/autoflake
rev: v1.7.1
rev: v1.7.6
hooks:
- id: autoflake
args:
Expand All @@ -64,7 +64,7 @@ repos:
- flake8-bugbear
- flake8-blind-except
- repo: https://github.com/asottile/pyupgrade
rev: v3.0.0
rev: v3.1.0
hooks:
- id: pyupgrade
args: [--py3-plus, --py38-plus, --keep-runtime-typing]
1 change: 1 addition & 0 deletions .readthedocs.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ build:
python: "3.10"
sphinx:
configuration: docs/conf.py
# disable this for more lenient docs builds
fail_on_warning: true
python:
install:
Expand Down
65 changes: 65 additions & 0 deletions docs/_templates/autosummary/class.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
{{ 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 %}
1 change: 1 addition & 0 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,4 +34,5 @@
:toctree: generated
pl.basic_plot
pl.BasicClass
```
40 changes: 32 additions & 8 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,11 @@
# -- Project information -----------------------------------------------------

info = metadata("cookiecutter-scverse-instance")
project = info["Name"]
project_name = info["Name"]
author = info["Author"]
copyright = f"{datetime.now():%Y}, {author}."
version = info["Version"]
repository_url = "https://github.com/" + "scverse" + "/" + project_name

# The full version, including alpha/beta/rc tags
release = info["Version"]
Expand All @@ -33,7 +34,7 @@
html_context = {
"display_github": True, # Integrate GitHub
"github_user": "scverse", # Username
"github_repo": project, # Repo name
"github_repo": project_name, # Repo name
"github_version": "main", # Version
"conf_py_path": "/docs/", # Path in the checkout to the docs root
}
Expand All @@ -43,15 +44,14 @@
# Add any Sphinx extension module names here, as strings.
# They can be extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
"myst_parser",
"myst_nb",
"sphinx_copybutton",
"sphinx.ext.autodoc",
"sphinx.ext.intersphinx",
"sphinx.ext.autosummary",
"sphinx.ext.napoleon",
"sphinxcontrib.bibtex",
"sphinx_autodoc_typehints",
"scanpydoc.definition_list_typed_field",
"nbsphinx",
"sphinx.ext.mathjax",
*[p.stem for p in (HERE / "extensions").glob("*.py")],
]
Expand All @@ -65,13 +65,31 @@
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_enable_extensions = [
"amsmath",
"colon_fence",
"deflist",
"dollarmath",
"html_image",
"html_admonition",
]
myst_url_schemes = ("http", "https", "mailto")
nb_output_stderr = "remove"
nb_execution_mode = "off"
nb_merge_streams = True
typehints_defaults = "braces"

source_suffix = {
".rst": "restructuredtext",
".ipynb": "myst-nb",
".myst": "myst-nb",
}

intersphinx_mapping = {
"anndata": ("https://anndata.readthedocs.io/en/stable/", None),
"numpy": ("https://numpy.org/doc/stable/", None),
}

nbsphinx_execute = "never"

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
Expand All @@ -84,10 +102,16 @@
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = "furo"
html_theme = "sphinx_book_theme"
html_static_path = ["_static"]
html_title = project_name

html_theme_options = {
"repository_url": repository_url,
"use_repository_button": True,
}

pygments_style = "sphinx"
pygments_style = "default"

nitpick_ignore = [
# If building the documentation fails because of a missing link that is outside your control,
Expand Down
11 changes: 5 additions & 6 deletions docs/developer_docs.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ On the RTD dashboard choose "Import a Project" and follow the instructions to ad
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_

Expand Down Expand Up @@ -289,24 +290,22 @@ Please write documentation for your package. This project uses [sphinx][] with t

- 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 [nbsphinx][] (See [Tutorials with nbsphinx](#tutorials-with-nbsphinx-and-jupyter-notebooks))
- 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 nbsphinx and jupyter notebooks
### Tutorials with myst-nb and jupyter notebooks

The documentation is set-up to render jupyter notebooks stored in the `docs/notebooks` directory using [nbsphinx][].
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.

[nbsphinx]: https://github.com/spatialaudio/nbsphinx

#### Hints

- If you refer to objects from other packages, please add an entry to `intersphinx_mapping` in `docs/conf.py`. Only
Expand All @@ -329,7 +328,7 @@ open _build/html/index.html
[codecov docs]: https://docs.codecov.com/docs
[pre-commit.ci]: https://pre-commit.ci/
[readthedocs.org]: https://readthedocs.org/
[nbshpinx]: https://github.com/spatialaudio/nbsphinx
[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
Expand Down
Empty file removed docs/extensions/.gitkeep
Empty file.
29 changes: 29 additions & 0 deletions docs/extensions/typed_returns.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# code from https://github.com/theislab/scanpy/blob/master/docs/extensions/typed_returns.py
# with some minor adjustment
import re

from sphinx.application import Sphinx
from sphinx.ext.napoleon import NumpyDocstring


def _process_return(lines):
for line in lines:
m = re.fullmatch(r"(?P<param>\w+)\s+:\s+(?P<type>[\w.]+)", line)
if m:
# Once this is in scanpydoc, we can use the fancy hover stuff
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)
if lines and lines[-1]:
lines.append("")
return lines


def setup(app: Sphinx):
"""Set app."""
NumpyDocstring._parse_returns_section = _parse_returns_section
Loading

0 comments on commit 3b6369e

Please sign in to comment.