Fix ALL Sphinx warnings #393

melissawm · 2024-04-06T23:31:46Z

References and relevant issues

Closes #111
Addresses #227 (will need a follow-up turning on sphinx -W option)

Description

This PR includes fixes to broken references and markdown syntax fixes. It also includes a new filter for napari.qt.threading module docstrings that were creating a few syntax warnings. These are not easily ignored by Sphinx and can't be fixed, as they are Markdown being injected into rst docstrings through the napari.qt module.

After this is merged, we will be able to make the build docs CI check to fail on new warnings, and new errors will be more visible.

lucyleeow · 2024-04-07T04:59:53Z

docs/conf.py

@@ -305,6 +308,38 @@ 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):


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.

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!

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!

psobolewskiPhD · 2024-04-07T16:19:02Z

Looking at CircleCI output:
https://app.circleci.com/pipelines/github/melissawm/napari-docs/340/workflows/20e668a6-ad6f-4d21-bca7-31327ec1ed0a/jobs/328?invite=true#step-106-33254_29 Just 16 warnings! Down from >140!

Looks like a few are fixed by:
#388
and then a few more by:
napari/napari#6812

lucyleeow

Thank you!

melissawm · 2024-04-08T13:51:28Z

Look at this https://github.com/napari/docs/actions/runs/8600978497/job/23567119812?pr=393#step:9:1522 😍 Finally!

Czaki · 2024-04-08T18:10:41Z

This duplicated warning is signalig problem with cross references?

psobolewskiPhD · 2024-04-08T20:25:02Z

Interesting this barks:
https://github.com/napari/docs/actions/runs/8600978497/job/23567119812?pr=393#step:9:663

WARNING: autodoc: failed to import function '_testsupport.make_napari_viewer' from module 'napari.utils'; the following exception was raised:
No module named 'pytest'

The relevant code, as far as I can tell:

docs/docs/developers/contributing/testing.md

Lines 243 to 255 in 1c6155f

    
           #### `make_napari_viewer` 
        
           We provide a 
        
           [pytest fixture](https://docs.pytest.org/en/stable/explanation/fixtures.html) called 
        
           `make_napari_viewer` for tests that require the {class}`~napari.Viewer`. This 
        
           fixture is available globally and to all tests in the same environment that `napari` 
        
           is in (see [](test-organization) for details). Thus, there is no need to import it, 
        
           you simply include `make_napari_viewer` as a test function parameter, as shown in the 
        
           **Examples** section below: 
        
           ```{eval-rst} 
        
           .. autofunction:: napari.utils._testsupport.make_napari_viewer() 
        
           ```

And on napari.org/dev/ it's broken:
https://napari.org/dev/developers/contributing/testing.html#make-napari-viewer
But with this PR it's working!
https://output.circle-artifacts.com/output/job/54961a00-f23c-4027-bc52-acec2f1e3e84/artifacts/0/docs/docs/_build/html/developers/contributing/testing.html#make-napari-viewer

melissawm · 2024-04-08T22:25:41Z

This duplicated warning is signalig problem with cross references?

Not really. As far as I can tell, this happens because some Attributes and Properties have the same name, which confuses sphinx (which doesn't deal with Attributes very well). In addition, in some cases when you have subclasses that inherit the parent's docstrings this can also happen (since both objects will be documented with the same parameters/attributes). But I will confess that as much as I've investigated this, it seems like nobody really knows what's going on exactly, including me 😅 (see, for example, sphinx-doc/sphinx#7817 which is the closest I could find)

We could potentially fix this without ignoring the errors, but that would mean having multiple templates for different classes which would make the docs generation less automatic and more manual. Since these warnings do not impact the rendering of the docs, I think they are safe to ignore.

melissawm · 2024-04-08T22:29:02Z

Interesting this barks: napari/docs/actions/runs/8600978497/job/23567119812?pr=393#step:9:663
WARNING: autodoc: failed to import function '_testsupport.make_napari_viewer' from module 'napari.utils'; the following exception was raised:
No module named 'pytest'
The relevant code, as far as I can tell:

docs/docs/developers/contributing/testing.md

Lines 243 to 255 in 1c6155f

#### `make_napari_viewer`

We provide a

[pytest fixture](https://docs.pytest.org/en/stable/explanation/fixtures.html) called

`make_napari_viewer` for tests that require the {class}`~napari.Viewer`. This

fixture is available globally and to all tests in the same environment that `napari`

is in (see [](test-organization) for details). Thus, there is no need to import it,

you simply include `make_napari_viewer` as a test function parameter, as shown in the

**Examples** section below:

```{eval-rst}

.. autofunction:: napari.utils._testsupport.make_napari_viewer()

```

And on napari.org/dev/ it's broken:
napari.org/dev/developers/contributing/testing.html#make-napari-viewer
But with this PR it's working!
output.circle-artifacts.com/output/job/54961a00-f23c-4027-bc52-acec2f1e3e84/artifacts/0/docs/docs/_build/html/developers/contributing/testing.html#make-napari-viewer

I think we'd have to include pytest as a dependency for building the docs for this to work without this warning? Not sure why I didn't see this locally...

psobolewskiPhD · 2024-04-08T22:33:28Z

I think we'd have to include pytest as a dependency for building the docs for this to work without this warning? Not sure why I didn't see this locally...

Local build instructions use dev install of napari, so you probably have it.
Edit: derp, so does circleCI workflow:

docs/.circleci/config.yml

Line 35 in 1c6155f

python -m pip install -e "napari/[pyside,dev]"

🤷

lucyleeow · 2024-04-09T00:26:26Z

is happens because some Attributes and Properties have the same name, which confuses sphinx (which doesn't deal with Attributes very well). In addition, in some cases when you have subclasses that inherit the parent's docstrings this can also happen

Maybe we could add this info in the FilterSphinxWarnings docstring?

This PR includes fixes to broken references and markdown syntax fixes. It also includes a new filter for napari.qt.threading module docstrings that were creating a few syntax warnings. These are not easily ignored by Sphinx and can't be fixed, as they are Markdown being injected into rst docstrings through the napari.qt module.

melissawm · 2024-04-11T13:28:34Z

@lucyleeow let me know if this is enough or if I should elaborate!

lucyleeow

LGTM!

psobolewskiPhD

everything looks good to me -- and it's working!
Thanks!!

psobolewskiPhD · 2024-04-12T01:27:26Z

SO I don't get the lxml warning:
https://github.com/napari/docs/actions/runs/8647550683/job/23709258930?pr=393#step:9:120

I tested locally and I also get it, but yet both lxml and lxml_html_clean are installed.

Why is it referring to html-clean? it's [html_clean] in the requirements.txt which matches their setup.py
It is a wierd setup.py, so maybe we should just use lxml_html_clean directly?

melissawm · 2024-04-12T14:39:51Z

I don't get this warning locally - but it looks like changing that requirement did it!

psobolewskiPhD

Everything looks good, so this is great, will make real warnings be so much more obvious now.

lucyleeow · 2024-04-16T00:26:04Z

ping @psobolewskiPhD could this go in? 😬

psobolewskiPhD · 2024-04-16T00:43:06Z

Yeah sorry; i'm terrible at circling back to merge things.

melissawm requested a review from psobolewskiPhD April 6, 2024 23:31

github-actions bot assigned melissawm Apr 6, 2024

github-actions bot added the documentation Improvements or additions to documentation label Apr 6, 2024

melissawm requested a review from lucyleeow April 6, 2024 23:32

melissawm mentioned this pull request Apr 6, 2024

Fix some rst syntax in docstrings napari/napari#6812

Merged

lucyleeow mentioned this pull request Apr 7, 2024

Fix broken cross links in docs #392

Closed

lucyleeow reviewed Apr 7, 2024

View reviewed changes

Czaki added this to the 0.5.0 milestone Apr 7, 2024

lucyleeow approved these changes Apr 8, 2024

View reviewed changes

melissawm force-pushed the fix-broken-refs branch from b4f7a69 to a9aa9ec Compare April 8, 2024 13:30

melissawm added 2 commits April 11, 2024 10:25

Add more information to FilterSphinxWarnings docstring

32ec08c

melissawm force-pushed the fix-broken-refs branch from a9aa9ec to 32ec08c Compare April 11, 2024 13:28

lucyleeow approved these changes Apr 11, 2024

View reviewed changes

psobolewskiPhD approved these changes Apr 12, 2024

View reviewed changes

psobolewskiPhD added the ready to merge label Apr 12, 2024

lucyleeow mentioned this pull request Apr 12, 2024

Update app-model doc with new information about _mock_app fixture #403

Merged

Add lxml_html_clean as an explicit requirement

80bd6e5

psobolewskiPhD approved these changes Apr 12, 2024

View reviewed changes

psobolewskiPhD merged commit c9e562d into napari:main Apr 16, 2024
7 checks passed

psobolewskiPhD removed the ready to merge label Apr 16, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix ALL Sphinx warnings #393

Fix ALL Sphinx warnings #393

melissawm commented Apr 6, 2024 •

edited

Loading

lucyleeow Apr 7, 2024

melissawm Apr 7, 2024

lucyleeow Apr 8, 2024

psobolewskiPhD commented Apr 7, 2024

lucyleeow left a comment

melissawm commented Apr 8, 2024

Czaki commented Apr 8, 2024

psobolewskiPhD commented Apr 8, 2024 •

edited

Loading

melissawm commented Apr 8, 2024 •

edited

Loading

melissawm commented Apr 8, 2024

psobolewskiPhD commented Apr 8, 2024 •

edited

Loading

lucyleeow commented Apr 9, 2024

melissawm commented Apr 11, 2024

lucyleeow left a comment

psobolewskiPhD left a comment

psobolewskiPhD commented Apr 12, 2024 •

edited

Loading

melissawm commented Apr 12, 2024

psobolewskiPhD left a comment

lucyleeow commented Apr 16, 2024

psobolewskiPhD commented Apr 16, 2024

Fix ALL Sphinx warnings #393

Fix ALL Sphinx warnings #393

Conversation

melissawm commented Apr 6, 2024 • edited Loading

References and relevant issues

Description

lucyleeow Apr 7, 2024

Choose a reason for hiding this comment

melissawm Apr 7, 2024

Choose a reason for hiding this comment

lucyleeow Apr 8, 2024

Choose a reason for hiding this comment

psobolewskiPhD commented Apr 7, 2024

lucyleeow left a comment

Choose a reason for hiding this comment

melissawm commented Apr 8, 2024

Czaki commented Apr 8, 2024

psobolewskiPhD commented Apr 8, 2024 • edited Loading

melissawm commented Apr 8, 2024 • edited Loading

melissawm commented Apr 8, 2024

psobolewskiPhD commented Apr 8, 2024 • edited Loading

lucyleeow commented Apr 9, 2024

melissawm commented Apr 11, 2024

lucyleeow left a comment

Choose a reason for hiding this comment

psobolewskiPhD left a comment

Choose a reason for hiding this comment

psobolewskiPhD commented Apr 12, 2024 • edited Loading

melissawm commented Apr 12, 2024

psobolewskiPhD left a comment

Choose a reason for hiding this comment

lucyleeow commented Apr 16, 2024

psobolewskiPhD commented Apr 16, 2024

melissawm commented Apr 6, 2024 •

edited

Loading

psobolewskiPhD commented Apr 8, 2024 •

edited

Loading

melissawm commented Apr 8, 2024 •

edited

Loading

psobolewskiPhD commented Apr 8, 2024 •

edited

Loading

psobolewskiPhD commented Apr 12, 2024 •

edited

Loading