scikit-image 0.22 docset seems to lack API docs about dash-user-contributions

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

[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

[ivaquero]

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

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

This time everything works fine.

[jni]

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

[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! 🙏)

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

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