diff --git a/docs/basics/101-135-help.rst b/docs/basics/101-135-help.rst index fc3fac9d7..76a781cdb 100644 --- a/docs/basics/101-135-help.rst +++ b/docs/basics/101-135-help.rst @@ -241,10 +241,11 @@ It is common for :command:`datalad get` errors to originate in :term:`git-annex` - The version number contains the release date of the version in use. For instance, git-annex version: ``8.20200330-g971791563`` was released on 30 March 2020. - If the version that you are using is older than a few months, consider updating using the instructions `here `_. - Try to download the file using ``git-annex get -v -d ``. If this doesn't succeed, the DataLad command may not succeed. Options ``-d/--debug`` and ``-v`` are here to provide as much verbosity in error messages as possible -- Read the output of :term:`git-annex`, identify the error, breathe again, and solve the issue! +- Read the output of :term:`git-annex`, identify the error, breathe again, and solve the issue! :numref:`table-gitannex-errors` list a few common or tricky ones. .. tabularcolumns:: \Y{.5}\Y{.5} -.. list-table:: Examples of possible issues +.. list-table:: Examples of possible git-annex issues. + :name: table-gitannex-errors :header-rows: 1 * - git-annex error diff --git a/docs/beyond_basics/101-145-hooks.rst b/docs/beyond_basics/101-145-hooks.rst index e13d1fcc0..f52e023f4 100644 --- a/docs/beyond_basics/101-145-hooks.rst +++ b/docs/beyond_basics/101-145-hooks.rst @@ -50,10 +50,16 @@ whenever an evaluation fulfills your criteria. To be able to specify matching criteria, you need to be aware of the potential criteria you can match against. The evaluation report is a dictionary with -``key:value`` pairs. The following table provides an overview on some of the -available keys and their possible values [#f1]_: - -.. list-table:: +``key:value`` pairs. :numref:`table-result-keyvalues` provides an overview on +some of the available keys and their possible values. + +.. tabularcolumns:: \Y{.33}\Y{.66} +.. list-table:: Common result keys and their values. This is only a selection of + available key-value pairs. The actual set of possible key-value pairs is + potentially unlimited, as any third-party extension could introduce new keys, + for example. If in doubt, use the ``-f/--output-format`` option with the + command of your choice to explore how your matching criteria may look like. + :name: table-result-keyvalues :widths: 50 100 :header-rows: 1 @@ -179,13 +185,6 @@ you defined), into the new dataset. .. rubric:: Footnotes - -.. [#f1] The key-value table provides a selection of available key-value pairs, but - the set of possible key-value pairs is potentially unlimited, as any - third-party extension could introduce new keys, for example. If in doubt, - use the ``-f/--output-format`` option with the command of your choice to - explore how your matching criteria may look like. - .. [#f2] It only needs to be compatible with :command:`git config`. This means that it for example should not contain any dots (``.``). diff --git a/docs/book_appendix.rst b/docs/book_appendix.rst index eb011e389..8b890b57f 100644 --- a/docs/book_appendix.rst +++ b/docs/book_appendix.rst @@ -12,3 +12,13 @@ Appendix contributing teaching acknowledgements + +.. raw:: latex + + \chapter{Boxes, Figures, Tables} + \tcblistof[\section]{gitusernotes}{List of notes for Git users} + \tcblistof[\section]{findoutmores}{List of info boxes} + \tcblistof[\section]{windowsworkarounds}{List of Windows workarounds} + + \listoffigures + \listoftables diff --git a/docs/conf.py b/docs/conf.py index ac7aa5722..988220fda 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -328,6 +328,8 @@ 'fncychap': r'\usepackage[Bjarne]{fncychap}', 'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}', 'preamble': r""" +\usepackage[labelfont=bf,singlelinecheck=false]{caption} +\renewcommand{\sphinxstyletheadfamily}{\bfseries} \usepackage{charter} \usepackage[defaultsans]{lato} \usepackage{inconsolata} @@ -406,6 +408,10 @@ \end{center}} \newcommand*\ruleline[1]{\par\noindent\raisebox{.8ex}{\makebox[\linewidth]{\hrulefill\hspace{1ex}\raisebox{-.8ex}{#1}\hspace{1ex}\hrulefill}}} \newenvironment{colortext}{\color{orange}}{\ignorespacesafterend} + + +\numberwithin{table}{chapter} +\numberwithin{figure}{chapter} """, } @@ -467,7 +473,7 @@ # Allow duplicate toc entries. #epub_tocdup = True -todo_include_todos = True +todo_include_todos = False intersphinx_mapping = { 'python': ('https://docs.python.org/3', None), diff --git a/docs/extension_pkgs.rst b/docs/extension_pkgs.rst index 71fec9d2e..2e29f4d68 100644 --- a/docs/extension_pkgs.rst +++ b/docs/extension_pkgs.rst @@ -7,7 +7,8 @@ DataLad extensions The commands DataLad provides cover a broad range of domain-agnostic use cases. However, there are extension packages that can add (domain-specific) -functionality and new commands. +functionality and new commands. :numref:`table-datalad-extensions` lists a number of +available extensions. Such extensions are shipped as separate Python packages, and are *not* included in DataLad itself. Instead, users with the need for a particular extension can @@ -27,21 +28,20 @@ of the package, no additional setup is required. Contributions of sections, chapters, or demonstrations for extensions that do not yet have one in the handbook are highly welcomed. -Among others (a full list can be found on `PyPi `_), -the following DataLad extensions are available: - -.. list-table:: +.. tabularcolumns:: \Y{.2}\Y{.8} +.. list-table:: Selection of available DataLad extensions. A more up-to-date list can be found on `PyPi `__ + :name: table-datalad-extensions :widths: 50 100 :header-rows: 1 - * - Extension name + * - Name - Description - * - `DataLad Container `_ + * - `container `_ - Equips DataLad's :command:`run`/:command:`rerun` functionality with the ability to transparently execute commands in containerized computational environments. The section :ref:`containersrun` demonstrates how this extension can be used, as well as the usecase :ref:`usecase_reproduce_neuroimg`. - * - `DataLad Crawler `_ + * - `crawler `_ - One of the initial goals behind DataLad was to provide access to already existing data resources. With :command:`crawl-init`/:command:`crawl` commands, this extension @@ -51,64 +51,68 @@ the following DataLad extensions are available: on `datasets.datalad.org `_ are created and updated using this extension functionality. - .. todo:: - - contribute a section or a demo, e.g. based on `existing one `__ - - * - `DataLad Neuroimaging `_ + * - `neuroimaging `_ - Metadata extraction support for a range of standards common to neuroimaging data. The usecase :ref:`usecase_reproduce_neuroimg` demonstrates how this extension can be used. - * - `DataLad Hirni `_ + * - `hirni `_ - A neuroimaging specific extension to allow reproducible DICOM to BIDS conversion of (f)MRI data. The chapter ... introduces this extension. - .. todo:: - - link hirni chapter once done - - * - `DataLad Metalad `_ + * - `metalad `_ - Equips DataLad with an alternative command suite and advanced tooling for metadata handling (extraction, aggregation, reporting). - .. todo:: - - once section on metadata is done, link it here - - * - `DataLad XNAT `_ + * - `xnat `__ - Equips DataLad with a set of commands to track `XNAT `_ projects. An alternative, more basic method to retrieve data from an XNAT server is outlined in section :ref:`providers`. - * - `DataLad UKBiobank `_ + * - `ukbiobank `__ - Equips DataLad with a set of commands to obtain and monitor imaging data releases of the `UKBiobank `_. An introduction can be found in chapter - .. todo:: - - link UKB chapter once done - - * - `DataLad htcondor `_ + * - `htcondor `__ - Enhances DataLad with the ability for remote execution via the job scheduler `HTCondor `_. - * - `DataLad's Git-remote-clone `_ helper + * - `rclone-remote `_ - Enables DataLad to push and pull to all third party providers with no native Git support that are supported by `rclone `_. - .. todo:: - - Rewrite Third Party chapter to use this helper - - * - `DataLad OSF `_ + * - `osf `_ - Enables DataLad to interface and work with the `Open Science Framework `_. Use it to publish your dataset's data to an OSF project, thus utilizing the OSF for dataset storage and sharing. - .. todo:: - Contribute a usecase or a demo when done. + +.. todo:: + + contribute a section or a demo, e.g. based on `existing one `__ + +.. todo:: + + link hirni chapter once done + + +.. todo:: + + once section on metadata is done, link it here + +.. todo:: + + link UKB chapter once done + +.. todo:: + + Rewrite Third Party chapter to use this helper + +.. todo:: + + Contribute a usecase or a demo when done. + To install a DataLad extension, use