Skip to content

docs: Resolve Docs build warnings #1427

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

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

docs: Resolve Docs build warnings #1427

wants to merge 8 commits into from

Conversation

Azaya89
Copy link
Contributor

@Azaya89 Azaya89 commented Jun 26, 2025

closes #1421

This PR attempts to resolve most of the warnings and errors from the docs build.

Copy link

codecov bot commented Jun 26, 2025

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 88.47%. Comparing base (b72785a) to head (171fd24).

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 Azaya89 self-assigned this Jun 26, 2025
@Azaya89 Azaya89 added wishlist Valid features without a volunteer or sponsor and removed wishlist Valid features without a volunteer or sponsor labels Jun 26, 2025
@Azaya89
Copy link
Contributor Author

Azaya89 commented Jun 26, 2025

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...

image

@hoxbro
Copy link
Member

hoxbro commented Jun 27, 2025

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
Copy link
Member

maximlt commented Jun 27, 2025

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:

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
Copy link
Member

hoxbro commented Jun 27, 2025

@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
Copy link
Member

maximlt commented Jun 27, 2025

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
Copy link
Contributor Author

Azaya89 commented Jun 27, 2025

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
Copy link
Contributor Author

Azaya89 commented Jun 27, 2025

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

image

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:

image

@Azaya89 Azaya89 marked this pull request as ready for review June 27, 2025 18:55
@Azaya89 Azaya89 requested a review from hoxbro June 27, 2025 18:56
@hoxbro
Copy link
Member

hoxbro commented Jun 27, 2025

Please fix the changelog before you ask for review.

Have you fixed the links @maximlt mentioned?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Resolve warnings emitted when building the docs
3 participants