Merge pull request #660 from datalad-handbook/bettertables

Bettertables

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 <http://handbook.datalad.org/en/latest/intro/installation.html>`_.
 - Try to download the file using ``git-annex get -v -d <file_name>``. 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

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 (``.``).
 

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

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),

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 <https://pypi.org/search/?q=datalad>`_),
-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 <https://pypi.org/search/?q=datalad>`__
+   :name: table-datalad-extensions
    :widths: 50 100
    :header-rows: 1
 
-   * - Extension name
+   * - Name
      - Description
-   * - `DataLad Container <http://docs.datalad.org/projects/container/en/latest/>`_
+   * - `container <http://docs.datalad.org/projects/container/en/latest/>`_
      - 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 <http://docs.datalad.org/projects/crawler/en/latest/>`_
+   * - `crawler <http://docs.datalad.org/projects/crawler/en/latest/>`_
      - 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 <http://datasets.datalad.org/>`_ are created and
        updated using this extension functionality.
 
-       .. todo::
-
-          contribute a section or a demo, e.g. based on `existing one <http://docs.datalad.org/projects/crawler/en/latest/demos/track_data_from_webpage.html>`__
-
-   * - `DataLad Neuroimaging <https://datalad-neuroimaging.readthedocs.io/en/latest/>`_
+   * - `neuroimaging <https://datalad-neuroimaging.readthedocs.io/en/latest/>`_
      - 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 <http://docs.datalad.org/projects/hirni/en/latest/>`_
+   * - `hirni <http://docs.datalad.org/projects/hirni/en/latest/>`_
      - 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 <http://docs.datalad.org/projects/metalad/en/latest/>`_
+   * - `metalad <http://docs.datalad.org/projects/metalad/en/latest/>`_
      - 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 <https://github.com/datalad/datalad-xnat>`_
+   * - `xnat <https://github.com/datalad/datalad-xnat>`__
      - Equips DataLad with a set of commands to track
        `XNAT <https://www.xnat.org/>`_ projects.
        An alternative, more basic method to retrieve data from an XNAT server is
        outlined in section :ref:`providers`.
-   * - `DataLad UKBiobank <https://github.com/datalad/datalad-ukbiobank>`_
+   * - `ukbiobank <https://github.com/datalad/datalad-ukbiobank>`__
      - Equips DataLad with a set of commands to obtain and monitor imaging data
        releases of the `UKBiobank <https://www.ukbiobank.ac.uk//>`_.
        An introduction can be found in chapter
 
-       .. todo::
-
-          link UKB chapter once done
-
-   * - `DataLad htcondor <https://github.com/datalad/datalad-htcondor>`_
+   * - `htcondor <https://github.com/datalad/datalad-htcondor>`__
      - Enhances DataLad with the ability for remote execution via the job
        scheduler `HTCondor <https://research.cs.wisc.edu/htcondor/>`_.
 
-   * - `DataLad's Git-remote-clone <https://github.com/datalad/git-remote-rclone>`_ helper
+   * - `rclone-remote <https://github.com/datalad/git-remote-rclone>`_
      - Enables DataLad to push and pull to all third party providers with no native Git
        support that are supported by `rclone <https://rclone.org/>`_.
 
-       .. todo::
-
-          Rewrite Third Party chapter to use this helper
-
-   * - `DataLad OSF <http://docs.datalad.org/projects/osf/en/latest/>`_
+   * - `osf <http://docs.datalad.org/projects/osf/en/latest/>`_
      - Enables DataLad to interface and work with the `Open Science Framework
        <https://osf.io/>`_. 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 <http://docs.datalad.org/projects/crawler/en/latest/demos/track_data_from_webpage.html>`__
+
+.. 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