======================================================================================= Reproducible publications: including and linking to provenance information in documents ======================================================================================= Sumatra provides tools to include figures and other results generated by Sumatra-tracked computations in documents, with links to full provenance information: i.e. the full details of the code, input data and computational environment used to generate the figure/result. LaTeX ----- To include figures from a Sumatra project in a LaTeX document, copy the file :file:`sumatra.sty` from the :file:`sumatra/publishing/latex` directory in the Sumatra source distribution into your working directory, then add .. code-block:: latex \usepackage{sumatra} in the preamble of your LaTeX document. If your LaTeX working directory is not the same as your Sumatra project directory, you can specify the location of the record store and the project name as package options: .. code-block:: latex \usepackage[recordstore=/path/to/db, project=MyProject]{sumatra} You can then use the ``\smtincludegraphics`` command in place of the usual ``\includegraphics``: .. code-block:: latex \smtincludegraphics{20120907-153528:my_figure.png} Here the argument is the label of a Sumatra record. This command will look up the record in your Sumatra project, find the location of the image file (whether a local file path or a URL) and include the figure in the document. If you are using the :class:`HttpRecordStore`, the figure will also be a hyperlink to the corresponding Sumatra record, so you can easily check the full provenance of the figure. If :file:`my_figure.png` is the only image file produced by that Sumatra run, then you can use just: .. code-block:: latex \smtincludegraphics{20120907-153528} without the path part. You can also use just a fragment of the image file name as a query term, replacing the ":" separator with "?": .. code-block:: latex \smtincludegraphics{20120907-153528?my_fig} All the usual ``\includegraphics`` options are supported, e.g.: .. code-block:: latex \smtincludegraphics[width=\textwidth]{20120907-153528:my_figure.png} You can also include as an option the SHA1 hash of the image file contents, as captured by Sumatra, to ensure that the image you include is the correct one, and that it hasn't been accidentally overwritten or replaced by another: .. code-block:: latex \smtincludegraphics[width=\textwidth, digest=e2d1054c2893f19f50c43ddd5a344b59383df648]{20120907-153528:my_figure.png} .. note:: you will have to run :command:`latex`/:command:`pdflatex` with the :option:`-shell-escape` option. .. todo:: mention that you can mix projects in a single document by providing the project name as an option to ``\smtincludegraphics`` Sphinx ------ To include figures from a Sumatra project, or links to Sumatra records of simulations or analyses, in a Sphinx_ document, you should first add ``'sumatra.publishing.sphinxext'`` to the ``extensions`` list in your :file:`conf.py` and then set the following options: .. code-block:: python sumatra_record_store = "/path/to/record/store" sumatra_project = "MyProject" sumatra_link_icon = "icon_info.png" .. todo:: link_icon should be optional: should have a default shipped with Sumatra The :mod:`sumatra.publishing.sphinxext` extension provides a reStructuredText directive :rst:dir:`smtimage` and a reStructuredText role :rst:role:`smtlink` The smtimage directive ~~~~~~~~~~~~~~~~~~~~~~ :rst:dir:`smtimage` includes an image file retrieved from a Sumatra project in your document. If you are using the :class:`HttpRecordStore`, the image will also be a hyperlink to the corresponding Sumatra record. .. code-block:: rest .. smtimage:: 20120907-153528:my_figure.png All the usual options to the normal :rst:dir:`image` directive can be used ('width', 'height, 'align', etc.), as well as the Sumatra-specific options "digest" (which is used to check the identity of the included image, as detailed in the section on LaTeX above) "record_store" and "project", which can be used to over-ride the global options specified in :file:`conf.py`, and so mix results from multiple projects in a single document. Here is a rather complete example. .. todo:: include link to documentation for image directive .. code-block:: rest .. smtimage:: 20120907-153528?my_fig :record_store: http://sumatra.example.com/ :project: MyOtherProject :digest: e2d1054c2893f19f50c43ddd5a344b59383df648 :width: 800 px :align: center :class: some-css-class The smtlink role ~~~~~~~~~~~~~~~~ If using a :class:`HttpRecordStore`, the :rst:role:`smtlink` role inserts an icon in the document, which is a hyperlink to a given record in the store. To use this, you must set the `sumatra_link_icon` option, as discussed above. .. _Sphinx: http://sphinx-doc.org