Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix ALL Sphinx warnings #393

Merged
merged 3 commits into from
Apr 16, 2024
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,13 @@
from importlib.metadata import distribution
from pathlib import Path
from urllib.parse import urlparse, urlunparse
import logging

from jinja2.filters import FILTERS
from sphinx_gallery import scrapers
from sphinx_gallery.sorting import ExampleTitleSortKey
from sphinx.highlighting import lexers
from sphinx.util import logging as sphinx_logging
from packaging.version import parse as parse_version
from pygments.lexers import TOMLLexer

Expand Down Expand Up @@ -226,6 +228,7 @@ def get_supported_python_versions(project_name):
'.jupyter_cache',
'jupyter_execute',
'plugins/_*.md',
'plugins/building_a_plugin/_layer_data_guide.md',
'gallery/index.rst',
]

Expand Down Expand Up @@ -305,6 +308,40 @@ def add_google_calendar_secrets(app, docname, source):
if docname == 'community/meeting_schedule':
source[0] = source[0].replace('{API_KEY}', GOOGLE_CALENDAR_API_KEY)

class FilterSphinxWarnings(logging.Filter):
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought you could filter warnings like this: https://github.com/sphinx-gallery/sphinx-gallery/pull/521/files

But I can't yet find documentation on this.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Usually yes - but this warning in particular you can't (or I couldn't!). See https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-suppress_warnings for a list of warnings that can be explicitly silenced. I think it falls into a similar category as sphinx-doc/sphinx#9750 - if you find a way to filter it, that would be great!

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh man I didn't know any of this. Using warnings.filterwarnings in the conf.py file - how does this even work? I can't find documentation of this. Is this a Sphinx thing?

I guess in sphinx-gallery/sphinx-gallery#521 , the warning is passed on by the extension Sphinx-Gallery? In the Sphinx docs it says:

Then extensions can also define their own warning types.

Does that mean that extension warning types are also able to be suppressed?

Anyway, I had no idea, this seems reasonable way to fix it AFAICT! Thanks!

"""Filter 'duplicate object description' warnings.

These warnings are a result of autosummary limitations when we have
Attributes and Properties in a class sharing the same name.

The warnings are not useful - they don't result in any missing documentation
or rendering issues, so we can safely ignore them.

"""
def __init__(self, app):
self.app = app
super().__init__()

def filter(self, record: logging.LogRecord) -> bool:
msg = record.getMessage()

filter_out = (
"duplicate object description",
)

if msg.strip().startswith(filter_out):
return False
return True

def qt_docstrings(app, what, name, obj, options, lines):
"""Only show first line of Qt threading docstrings.

Avoids syntax errors since the Qt threading docstrings are written in
Markdown, and injected into rst docstring automatically.
"""
if "WorkerBase" in name:
if len(lines) > 0:
del lines[1:]

def setup(app):
"""Set up docs build.
Expand All @@ -313,11 +350,21 @@ def setup(app):
files found for document when generating the gallery
* Rewrites github anchors to be comparable
* Adds google calendar api key to meetings schedule page
* Filters out 'duplicate object description' Sphinx warnings
* Cleans out Qt threading docstrings

"""
app.registry.source_suffix.pop(".ipynb", None)
app.connect('source-read', add_google_calendar_secrets)
app.connect('linkcheck-process-uri', rewrite_github_anchor)
app.connect('autodoc-process-docstring', qt_docstrings)
logger = logging.getLogger("sphinx")

warning_handler, *_ = [
h for h in logger.handlers
if isinstance(h, sphinx_logging.WarningStreamHandler)
]
warning_handler.filters.insert(0, FilterSphinxWarnings(app))


def get_attributes(item, obj, modulename):
Expand Down
2 changes: 1 addition & 1 deletion docs/developers/architecture/app_model.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ Currently, the primary purpose of the `app` is to compose the following
[commands](app-model-commands) (the actual callable objects) that have been
registered with the application. Accessible via `app.commands`.
* {class}`~app_model.registries.MenusRegistry`: maintains all of the
[menus and submenus](appp-model-menus) that have been registered with the application.
[menus and submenus](app-model-menus) that have been registered with the application.
Accessible via `app.menus`.
* {class}`~app_model.registries.KeyBindingsRegistry`: maintains the association
between a [KeyBinding](app-model-keybindings) and a command ID in the
Expand Down
20 changes: 9 additions & 11 deletions docs/naps/9-multiple-canvases.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ Providing native support in napari would allow developers to more easily create
* There will be no possibility of a viewer with no canvases.
* Users shall be able to add, remove, and (maybe[^maybe-rearrange]) rearrange canvases.

[^maybe-rearrange]: Exact UI/UX may is yet to be decided, see [UI Architecture](#UI-Design-and-Architecture) for some discussion.
[^maybe-rearrange]: Exact UI/UX may is yet to be decided, see [UI Architecture](#ui-design-and-architecture) for some discussion.

### Design Considerations & Decisions
Part of this design document is intended to capture the desired behavior and prevent scope creep. At the extreme “multiple canvases” can be achieved with “multiple viewers”. Therefore we need to draw a line somewhere to differentiate a “canvas” from a “viewer”. [^napari-lite]
Expand All @@ -96,10 +96,9 @@ In addition to maintaining the model-view-controller (MVC) architecture of napar
### Architecture
napari architecture is based on the MVC pattern. The model layer comprises a `ViewerModel` and a list of Layer models (subclasses of a base `Layer`). There are seven layer types, each with a corresponding view type. Currently models and views are paired 1:1, and the correlation is stored in a map (`layer_to_visual`) on the `VispyCanvas`. Figure 1 shows the class relationships for the base model types and the Image layer types (for brevity - other layer types have similar connectivity).

```{image} _static/multicanvas-napari-architecture-today.png
---
name: fig-1
---
```{figure} _static/multicanvas-napari-architecture-today.png
:name: nap-9-fig-1

Fig. 1: napari architecture today.
```

Expand All @@ -119,10 +118,9 @@ Figure 2 shows proposed changes (in orange) to the architecture to support multi
* Callbacks (interaction, events) will need to be specifically connected to individual `CanvasModel` objects where relevant (dims, camera) rather than the `ViewerModel`.


```{image} _static/multicanvas-napari-architecture-tomorrow.png
---
name: fig-2
---
```{figure} _static/multicanvas-napari-architecture-tomorrow.png
:name: nap-9-fig-2

Fig. 2: napari architecture tomorrow, with proposed changes from this NAP highlighted in orange.
```

Expand Down Expand Up @@ -165,7 +163,7 @@ Slice state for each layer is currently stored on the Layer model. Again, see [N
> [name=Ashley A]

### UI Design and Architecture
Specific UI design and architecture remains to be determined. This will be explored as part of step 4 in the [Implementation Plan](#Implementation). UI design needs additional refinement and exploration, and this is expected to continue after basic/core implementation propsed in this NAP is complete. UI changes may also be described in a separate NAP along with a discussion of convenience functions and affordances for common operations. Some placeholder or experimental code will be used in the meantime as a prototype implementation.
Specific UI design and architecture remains to be determined. This will be explored as part of step 4 in the [Implementation Plan](#implementation). UI design needs additional refinement and exploration, and this is expected to continue after basic/core implementation propsed in this NAP is complete. UI changes may also be described in a separate NAP along with a discussion of convenience functions and affordances for common operations. Some placeholder or experimental code will be used in the meantime as a prototype implementation.

Some open questions here are (for example):
* Should each canvas also have visible dims sliders, or can we keep one set of dims sliders that changes based on the active (selected) canvas?
Expand Down Expand Up @@ -221,7 +219,7 @@ See other image viewers for examples for multiple canvases (mostly demonstrating
* Update main widget as `ViewerModel` “active” canvas changes, storing additional canvases and swapping them out as necessary

4. Update `QtViewer` to show multiple canvases simultaneously
* This is exploratory work at the moment, see [UI Architecture](#UI-Design-and-Architecture) section below
* This is exploratory work at the moment, see [UI Architecture](#ui-design-and-architecture) section below

[^async-only]: Depending on the timeline and prototype implementation, it may be acceptable/preferable for multi-canvas feature to rely on (currently experimental) async slicing ([see NAP-4](https://napari.org/stable/naps/4-async-slicing.html)).

Expand Down
2 changes: 1 addition & 1 deletion docs/release/release_0_4_19.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ labels_layer = viewer.add_labels(
)
```

See the ["Deprecations" section below](#Deprecations) for more information on
See the ["Deprecations" section below](#deprecations) for more information on
the new API. ([#6542](https://github.com/napari/napari/pull/6542))

### More on colormaps!
Expand Down
3 changes: 1 addition & 2 deletions docs/tutorials/processing/dask.md
Original file line number Diff line number Diff line change
Expand Up @@ -205,7 +205,7 @@ directory. The dataset is 3.69 GB unzipped.
```

While we could use plain `dask` through `delayed`, as we have shown above, we
will [make our lives easier](make-your-life-easier-with-dask-image) here and use
will [make our lives easier](#make-your-life-easier-with-dask-image) here and use
`dask-image`.

Using [dask_image.imread](https://image.dask.org/en/latest/dask_image.imread.html#module-dask_image.imread),
Expand Down Expand Up @@ -326,4 +326,3 @@ ready to show you the result on demand!
- [Documentation on dask.delayed](https://docs.dask.org/en/latest/delayed.html)
- [Dask working notes on dask-image](https://blog.dask.org/2019/06/20/load-image-data)
- [Dask working notes on image processing with `dask.array.map_blocks`](https://blog.dask.org/2019/08/09/image-itk)
- [](brain_dataset_tutorial.md)
Loading