scikit-image 0.22 docset seems to lack API docs

[jni]

It looks like the latest update to the scikit-image docset broke API search (and other parts of the documentation, such as the gallery examples). Now I can no longer get API docs which imho are the most important use case for Dash.

If I search for "scikit-image", ie get suggestions from pages from the narrative docs in scikit-image:

However, as soon as I type a function from the API, I get no hits:

I presume that this all comes from an incomplete build of the docs, but it would be great if the docset could get updated ASAP to include the API and the gallery examples... 🙏

[Kapeli]

// cc @iamaziz @ivaquero

[ivaquero]

I will try to fix tomorrow.

[ivaquero]

Hi, @jni. I updated the docset. Here is the result on my Mac.

However, I my git fork is not clean (I don't know how to fix), I am not sure whether this will affect the merge.

#4713

[jni]

However, I my git fork is not clean (I don't know how to fix), I am not sure whether this will affect the merge.

Is it just a matter of copying the scikit-image.tgz from #4713 to a clean branch on a clean fork and adding that? Or are the other changes in that PR necessary? If we just need the .tgz file in a PR by itself, I'd be happy to do that. (I'm comfortable with open source development with git, I'm not (yet) comfortable with Dash docset creation. 😅)

[jni]

(Thank you for the update btw! 🙏)

[ivaquero]

You are welcome. I decided to delete the current fork and refork, and I need some more time to migrate my another two branches. I will finish as soon as possible.

These docsets are big ones.

[ivaquero]

The New PR #4716

[jni]

@ivaquero hmmm, I downloaded the new docset and it's still missing the API docs, even though the gallery is now there:

(And the gallery docs should link to the API docs and vice versa.)

[ivaquero]

Hi @jni, you are right, I just noticed the following error, though the docset generated successfully

But, I cannot find the api.rst in the source code downloaded from https://github.com/scikit-image/scikit-image. I remember that you are the core developer of skimage, could you please show me where I can find the doc/source/api/api.rst file ?

[jni]

Ah. That was trickier than I expected, sorry about that! 😅 I found one in my source dir but it had an ominous "Autogenerated file, do not edit" warning at the top, and indeed it's not in the source tree. 😅

It turns out we have a bit of machinery to autogenerate the API docs. I don't know why this is the case — perhaps @stefanv knows. I imagine it dates from a time when sphinx autogeneration was less robust, or, it's a workaround for our lazy import machinery.

Anyway, to run the machinery, cd into the doc/ directory and run make api:

https://github.com/scikit-image/scikit-image/blob/main/doc/Makefile#L43-L46

At that point you should (🤞) have everything you need to generate the full docset! 🙏

[ivaquero]

Hi @jni, I tried make api, however I got the following msg

python tools/build_modref_templates.py
*WARNING* API documentation not generated: Installed version does not match source version
Build API docs...done.

I tested python 3.11, python 3.12, scikit-image 0.21.0, scikit-image 0.22.0, the results are the same.

[jni]

Are you checking out the right tag? You need to (a) install scikit-image (v0.22.0), (b) check out the same version of the scikit-image source code (v0.22.0), then (c) run make api.

You can see the check that raises this error here:

https://github.com/scikit-image/scikit-image/blob/09577eddf2ce0376b25b96291599af313adb1c2d/doc/tools/build_modref_templates.py#L50-L51

The installed version is found by importing skimage and checking skimage.__version__ here, while the source version is found by parsing skimage.__init__.py to find the line defining __version__. If you look at that line in the v0.22 tag, you can see it is indeed 0.22.0.

So I suspect that you are just missing a git checkout v0.22.0 and then it should work!!! 🤞

[jni]

(Thank you for your help and patience!!! 🙏)

[ivaquero]

Are you checking out the right tag? You need to (a) install scikit-image (v0.22.0), (b) check out the same version of the scikit-image source code (v0.22.0), then (c) run make api.

You can see the check that raises this error here:

https://github.com/scikit-image/scikit-image/blob/09577eddf2ce0376b25b96291599af313adb1c2d/doc/tools/build_modref_templates.py#L50-L51

The installed version is found by importing skimage and checking skimage.__version__ here, while the source version is found by parsing skimage.__init__.py to find the line defining __version__. If you look at that line in the v0.22 tag, you can see it is indeed 0.22.0.

So I suspect that you are just missing a git checkout v0.22.0 and then it should work!!! 🤞

I used the main branch, ok, let me try the v0.22.0 tag.

[ivaquero]

(Thank you for your help and patience!!! 🙏)

You are welcome, I learnt a lot from your patient guide.

This time everything works fine.

[ivaquero]

The New PR: #4744

BTW, I deleted one Page (Interactive Plot, > 25 Mb) on purpose, or the docset size would be over 100 Mb. Although it recommended git-lfs (it's said not free) could handle this, I am too busy these days. Once I get more leisure time, I will try to find some work around, and rebuild the docset again.

[jni]

BTW, I deleted one Page (Interactive Plot, > 25 Mb) on purpose, or the docset size would be over 100 Mb.

This seems fine to me.

Although it recommended git-lfs (it's said not free) could handle this, I am too busy these days. Once I get more leisure time, I will try to find some work around, and rebuild the docset again.

btw I don't recommend lfs. git-annex seems to be a better option, but honestly I think it's ok to leave this page out of the docset.

[jni]

I can confirm that the docset in #4744 solves the problem! 🥳