Update docs #40
2024-01-10
Apply one more suggestion from code review
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>
Apply further suggestions from code review
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>
2023-12-19
docs: refactor datalad requirements
The DataLad access requirements are moved to a separate section, which is referenced in short paragraph by dataset generation and access sections.
docs: be more precise about requirements
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.
2023-12-18
docs: increase cohesion, adjust catalog mentions
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.
docs: update section on generating DataLad datasets
Adds software requirements and catalog generation, and a few lesser changes.
docs: create dedicated page for datalad credentials
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.
2023-12-15
Tweak admin docs
Emphasise the DataLad part being optional, add link to scripts and container pages for detailed information.
Split reference and admin docs into separate pages
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.
Rename admin docs to reference
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.
Rewrite datalad-based access
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.
2023-12-12
2023-11-29
Update docs requirements
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.
2023-11-27
Fix script names in documentation
This fixes a previous omission and updates usage help snippets to match documentation headings (and actual script names).