Add support for slideshows using sphinx-carousel

assigned to @lunar

mentioned in merge request swh-alter!1 (merged)

approved this merge request

This would be a nice addition to show the various steps of an algorithm in swh-alter documentation.

And other module documentations could also use that nice feature, LGTM.

enabled an automatic merge when the pipeline for 0bc1ec48 succeeds

Jenkins job DDOC/builds #365 failed .
See Console Output and Coverage Report for more details.

Diff’ing the previous output, we can see these new lines:

…
Creating file apidoc/swh.loader.svn.directory.rst.
…
/var/lib/jenkins/workspace/DDOC/builds/swh-docs/.tox/sphinx-dev/lib/python3.7/site-packages/swh/loader/svn/directory.py:docstring of swh.loader.svn.directory.SvnDirectoryLoader.snapshot:1: WARNING: more than one target found for cross-reference 'Snapshot': swh.fuse.fs.artifact.Snapshot, swh.model.model.Snapshot    
/var/lib/jenkins/workspace/DDOC/builds/swh-docs/.tox/sphinx-dev/lib/python3.7/site-packages/swh/loader/svn/directory.py:docstring of swh.loader.svn.directory.SvnDirectoryLoader.cnts:1: WARNING: more than one target found for cross-reference 'Content': swh.fuse.fs.artifact.Content, swh.model.from_disk.Content, swh.model.model.Content
/var/lib/jenkins/workspace/DDOC/builds/swh-docs/.tox/sphinx-dev/lib/python3.7/site-packages/swh/loader/svn/directory.py:docstring of swh.loader.svn.directory.SvnDirectoryLoader.dirs:1: WARNING: more than one target found for cross-reference 'Directory': swh.fuse.fs.artifact.Directory, swh.model.from_disk.Directory, swh.model.model.Directory
make: Leaving directory '/var/lib/jenkins/workspace/DDOC/builds/swh-docs/docs'
make: *** [Makefile:27: sphinx/html] Error 1

@ardumont My understanding so far is that it is related to swh-loader-svn@72dfc411 or swh-loader-core@abe741a9. Any idea?

Not really, no. It looks like sphinx's apidoc cannot detect which types is the correct one there... (which should be "mostly" the model ones).

In the swh.loader.core.loader.BaseDirectoryLoader, there is the declaration [1] with multiple imports. So that must confuse that sphinx plugin somehow.

[1]

from swh.model import from_disk
from swh.model.hashutil import hash_to_bytes
from swh.model.model import (
    Content,
    Directory,
    ExtID,
    Origin,
    OriginVisit,
    OriginVisitStatus,
    RawExtrinsicMetadata,
    Sha1Git,
    SkippedContent,
    Snapshot,
    SnapshotBranch,
    TargetType,
)

...
class BaseDirectoryLoader(NodeLoader):
...
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.directory: Optional[from_disk.Directory] = None
        self.cnts: List[Content] = None
        self.skipped_cnts: List[SkippedContent] = None
        self.dirs: List[Directory] = None

Maybe those should be moved to a dedicated module...

Annoyingly, this does not seem to happen when building the docs just in swh-loader-svn.

I wonder if something like the following would help:

from swh.model.from_disk import Directory as DirectoryFromDisk
# […]
        self.directory: Optional[DirectoryFromDisk] = None

That sphinx error is weird, it is confused by the fact that the swh-fuse package defines Content, Directory and Snapshot in https://gitlab.softwareheritage.org/swh/devel/swh-fuse/-/blob/master/swh/fuse/fs/artifact.py. Why sphinx do not yell for other swh modules importing those classes from the swh-model package ? Maybe it is only related to class member documentation ?

Annoyingly, this does not seem to happen when building the docs just in swh-loader-svn.

Yes, i had no issue with my mrs related to this.

I have a wip [1] with the code moved to a dedicated module but i don't like it and i have no idea if that'd help or not...

[1] swh-loader-core!473 (closed)

I wonder if something like the following would help:

yes, wondering too, it'd that'd be less impactful if that work. I've opened [2] if you wanna try something out as well out of it.

[2] swh-loader-core!474 (closed)

SvnDirectoryLoader inherits from BaseDirectoryLoader which inherits from NodeLoader, which defines: self.snapshot: Optional[Snapshot] = None and it loses the annotation's value (only keeps its string representation) because of the inheritence: https://github.com/sphinx-doc/sphinx/issues/10124