This adds a note to the datalad access documentation, advising users
that cloning from an incorrect datalad-annex URL will not cause an
error, but instead produce an empty repository.
Suggested-by: Adina Wagner <adina.wagner@t-online.de>
Apart from small formatting tweaks, this commit adds the following
changes to the dataladification workflow description:
- clarify dataset creation: the workflow creates dataset
representations that can be cloned, not checked-out datasets
- link to the singularity container description before using
singularity run for the first time
- add missing argument placeholders
- mention that the catalog needs to be served
Suggested-by: Adina Wagner <adina.wagner@t-online.de>
If datasets generated with ICF tooling are on local infrastructure,
then cloning datasets and accessing ICF are two separate things, but
both require DataLad-Next.
This unifies some spelling (local_dicom_store, uppercase DICOM), and
adds or tweaks some opening/closing paragraphs.
Catalog mention for browser-based access gets prefixed with an "if",
because it is unlikely that it will be generated for the ICF
datasets. I leave the paragraph nonetheless, to signal the
possibility.
Catalog mention for datalad based access is removed, because the
catalogify script hardcodes the (clone) URL to the ICF store URL, and
we are now assuming that the catalog generation happens on local
infrastructure.
In the current docs organisation we need to refer to credentials in
two pages: generating and accessing datasets. It makes sense to
elevate the credentials info (including an admonition about DataLad
access being equivalent to https access) to a separate page which can
be referenced in 1-2 sentences.
This reflects the fact that dataladification scripts are no longer
meant to be used by the ICF admins only - in fact, they are most
likely meant to be used by ICF users.
Apart from generating dicom tarballs, the icf tooling can be used by
either icf or its users to dataladify the datasets. Therefore, it
makes sense to rename the current "admin docs" (which mostly explain
containerized execution and included scripts) as
"reference". Following commits can break it down a bit more.
This changes the store base URL used in the examples from
https://data.inm-icf.de to file:///data/group/..., reflecting the fact
that the DataLad datasets are not provided by the ICF -- but they can
be generated on local infrastructure instead.
Title is changed (making it more similar to the previous section), and
some explanations are slightly tweaked.
Seeing that a build on Sphinx 7.0.1 succeeded, but a build on Sphinx
7.2.6 failed with Furo 2023.5.20 theme, I decided to bump furo version
and narrow down Sphinx to a minor release.
Furo changelog: https://pradyunsg.me/furo/changelog/
If you are reading this commit message and considering updating or
loosening the dependencies, then you probably should do it without
issues. I suppose even now an unpinned dependency would work; it's
probably on rare occasions when the released version of the theme
needs to catch up to Sphinx development, which likely caused us to
introduce pinning in first place. In either case, it would seem that
pinning Furo to a specific version, but Sphinx only to major release
is not a good idea.
