docs: Resolve Docs build warnings

[Azaya89]

closes #1421

This PR attempts to resolve most of the warnings and errors from the docs build, as well as some of the issues still pending in #1395

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 88.47%. Comparing base (b72785a) to head (413fe52).
Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1427   +/-   ##
=======================================
  Coverage   88.47%   88.47%           
=======================================
  Files          94       94           
  Lines       18692    18692           
=======================================
  Hits        16537    16537           
  Misses       2155     2155           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Azaya89]

Most of the remaining warnings are about external links that actually work and image files that actually render, so I'm not sure why the warnings are still there...

[hoxbro]

I'm not sure why the warnings are still there...

The patching likely happens after this warning. I don't think there's much we can do about it, other than checking to confirm that the patching is done correctly for all the warnings.

[maximlt]

WARNING: Source file for "https://holoviews.org)/ or [Bokeh](https://bokeh.org/) that provides interactive plots with dynamic zooming, labeled axes, and overlays and layouts ([Interactivity](./3_Interactivity.ipynb" not found (path relative to "/Users/runner/work/datashader/datashader/doc/getting_started")
WARNING: Source file for "https://pandas.pydata.org)/ or [Dask](https://dask.org/) dataframes, gridded multidimensional array data using [xarray](https://xarray.dev/), columnar data on GPUs using [cuDF](https://github.com/rapidsai/cudf), multidimensional arrays on GPUs using [CuPy](https://cupy.chainer.org/), and ragged arrays using [SpatialPandas](https://github.com/holoviz/spatialpandas) (see the [Performance User Guide](../user_guide/10_Performance.ipynb" not found (path relative to "/Users/runner/work/datashader/datashader/doc/getting_started")
...

I was really puzzled by these warnings. If you check these pages you will see they have broken links:

• https://datashader.org/getting_started/Introduction.html has a link with 3-Interactivity as text that is broken
• https://datashader.org/getting_started/Pipeline.html has a link with Performance User Guide as text that is broken

I'm not sure the first one ever worked, as it should have been 3_Interactivity (underscore instead of hyphen). The second one points to ../10_Performance.ipynb while it should have been ../user_guide/10_Performance.ipynb.

So it seems these warnings are not just noise but real doc bugs.

---

Side note, I forgot that nbsite has this feature that allows notebooks to be numbered (1_, 2_, ...) in the examples folder, but they don't appear as numbered on the website. For example, the notebook 2_Pipeline.ipynb ends up at the page Pipeline.html. For a short while I thought this part was broken but no it seems like it works as expected.

[hoxbro]

@maximlt, these warnings could be fixed in a newer nbsite release. I have set over a dev deployment so that we can check it.

Edit: Seems like they are still there.

[maximlt]

Yep I'm not sure how they could have been fixed by nbsite. At least for the two I checked, the links are clearly wrong and won't work in a Notebook or on the website.

[Azaya89]

Yep I'm not sure how they could have been fixed by nbsite. At least for the two I checked, the links are clearly wrong and won't work in a Notebook or on the website.

The ones you checked are different from the Source file.... errors. Those are 'myst' cross-reference target not found warnings that just happen to be in the same notebook as the other warnings. There are about 3 of these types of warnings still remaining that are still not yet fixed.

[Azaya89]

I converted the CHANGELOG file to markdown and that took care of the warnings about "Duplicate explicit target name".

However, I also noticed that the file is not properly parsed like a markdown file. Headers are not formatted properly and links don't show properly too, even though they work:

[hoxbro]

Please fix the changelog before you ask for review.

Have you fixed the links @maximlt mentioned?

[Azaya89]

Changelog file fixed.

As for the other 'myst' cross-reference target not found type warnings @maximlt pointed out, there are 3 of them and AFAICT, there's nothing wrong with the relative path links as they work locally. However, I also noticed that even though they don't work in the build, if you rebuild again immediately after, they become fixed. I suspect it has something to do with the _fix_links.py file in nbsite.

[hoxbro]

I think the fix links work; I just reran the dev webpage from this branch, and it looks good to me. Am I missing something?

I'm pretty sure this is what does the conversion of links: https://github.com/holoviz-dev/nbsite/blob/645a25a3b2e05721c08f9d8b2a2fbe0455761f61/nbsite/scripts/_fix_links.py#L110-L110

[hoxbro]

There was a problem in the nbsite, which I have fixed in holoviz-dev/nbsite#344

[hoxbro]

Some small comments. We shouldn't add the tiles notebook. If you want to add it, you can polish it and open a new PR with it.

[hoxbro]

Suggested change

	depends-on = ['_docs-install', '_docs-generate-rst', '_docs-generate']
	depends-on = ['_docs-generate-rst', '_docs-generate']
	[feature.doc.tasks.docs-build-full]
	depends-on = ['_docs-install', 'download-data', '_docs-generate-rst', '_docs-generate']

I would still want it to be able to run the docs without installing.

[Azaya89]

Some Deprecation warning is causing the tests to fail..

Edit: I think it was due to a new Pillow release. See python-pillow/Pillow#9018

[hoxbro]

Does this work for older versions of Pillow? Or should we version check it?

[hoxbro]

Have done some changes, lets see how the CI likes it.

[hoxbro]

I did not like it; I will revert the changes and address this in another PR.

[hoxbro]

Thank you for the work here 🔥

What was the final tally of warnings?

[Azaya89]

What was the final tally of warnings?

28, totally harmless, warnings.