Showyourwork

++++++++++++++++++

- Fixed ``string.removeprefix`` compatibility issue for Python 3.8.
- Upgraded ``click`` dependency to fix compatibility issue with decorators; added explicit dep on ``packaging`` package.
- Fixed issue with Zenodo latency when no ``$SANDBOX_TOKEN`` env variable defined.
- Fixed issue with conda channel priorities and UnsatisfiableError exceptions.
- Added support for SyncTeX.
- Added option to ignore certain files when rendering the article DAG.
- Added entries to the FAQs and cleaned up the docs a bit.
- Changelog: `v0.2.3...v0.3.0 <https://github.com/showyourwork/showyourwork/compare/v0.4.0...v0.4.1>`_

++++++++++++++++++

- **Major update to the versioning system** for ``showyourwork`` articles, and
to how dependencies are managed. As of this version, ``showyourwork`` no
longer manages its own ``conda`` environment -- this led to various
issues such as inconsistencies in the environment when the version of
``showyourwork`` used to launch the workflow differed from the version
specified *in* the workflow.
- Related to the change above, we no longer require workflows to be executed with the
same version of ``showyourwork`` that created them. From now on, workflows
will be executed with whatever version of ``showyourwork`` is
installed in the current environment (provided it is ``>=0.4.0``). We
are committed to make sure changes to the code are backwards compatible,
so the latest version of ``showyourwork`` will be able to execute any
workflow created with a previous version. This makes it **much** easier to
maintain the workflow, since any issues with the code or any of its
dependencies can be resolved by simply upgrading the locally installed version
(as opposed to having to patch all previous versions, for example
`here <https://github.com/showyourwork/showyourwork/issues/215>`__).
- The ``version`` setting in ``showyourwork.yml`` is no longer used (see above);
we recommend still including it, however, for bookkeeping purposes.
- For extended discussions about the above points, please see
`this issue <https://github.com/showyourwork/showyourwork/issues/214>`__
and the comments in
`this PR <https://github.com/showyourwork/showyourwork/pull/217>`__ and
`this PR <https://github.com/showyourwork/showyourwork/pull/221>`__.
- ``showyourwork`` no longer has explicit non-python dependencies; packages
like ``tectonic`` are specified within ``conda`` environments to specific rules,
so non-python dependency management is relegated to ``snakemake``.
- Now enforcing strict channel provenance in ``environment.yml`` files.
- Upgraded the pinned version of ``Snakemake`` to ``7.15.2``, which fixes
several bugs and adds new features
(such as `this one <https://github.com/showyourwork/showyourwork/issues/199>`__).
- Removes ``showyourwork`` logo and abstract margin icon in favor of a
``showyourwork`` stamp in the upper right hand corner of the first page
of the article. This approach is class-independent and fixes several issues
with specific classes (such as "Float(s) lost" errors with MNRAS and ARA&A).
The positioning and style of the stamp is configurable in
``showyourwork.yml``.
- Check if figure, abstract defined before redefining them; allows usage of
``showyourwork`` with document classes such as ``article``, which don't
define an ``abstract`` environment.
- Added GitHub margin links for ``\variable{}`` commands.
- The repository template now includes all available options (set to their
default values) in the ``showyourwork.yml`` config file.
- The preprocessing step is now automatically re-run when ``zenodo.yml``
changes.
- Miscellaneous bug fixes, docs improvements, and deprecation warning fixes.
- Changelog: `v0.3.1...v0.4.0 <https://github.com/showyourwork/showyourwork/compare/v0.3.1...v0.4.0>`_

++++++++++++++++++

- Fixed bug related to displaying figure caption icons for cached datasets.
- Added recursive dependency checks; if any upstream dependency of a figure script
is a dataset or cached Zenodo deposit, an icon to that dataset/deposit will
be displayed next to the figure.
- Added functionality to obtain the Snakemake DAG prior to running any of the
rules (used to infer upstream dependencies above). Metadata from the DAG is
stored in the global config.
- Reintroduced option to render the workflow DAG when building the article;
users can now provide DAG-related settings under the ``dag`` entry in the
config file (set ``render: true`` to enable the DAG generation).
Note that ``showyourwork`` now depends on the ``graphviz`` package, so users
may have to clear their ``~/.showyourwork`` cache to force regeneration of
the default ``showyourwork`` conda environment.
- Workaround for issue with incomplete files not getting deleted when passing
the ``--rerun-incomplete`` flag. Running ``showyourwork clean`` now deletes
the ``.snakemake/incomplete`` directory.
- Server errors on Zenodo / Zenodo Sandbox no longer lead to fatal errors when
accessing the remote file cache.
- Fixed issue with broken GitHub links in the PDF when using SSH to authenticate
with GitHub.
- Implemented better testing for showyourwork features; test repositories now
persist on GitHub (showyourwork/test-**).
- Implemented major fix for issue `124 <https://github.com/showyourwork/showyourwork/issues/124>`__,
which allows us to optimize the DAG by eliminating unnecessary jobs upstream
of jobs with cache hits.
- Users can now clone an empty remote repository prior to running ``showyourwork setup``
without triggering an error.
- Added option to pass custom arguments to the ``tectonic`` build.
- Removed dependency on ``fontspec``, which caused issues with TT fonts. The ``shoyourwork``
logo is no longer displayed as text in a custom font, but as a PDF image.
- Fix for newer versions of ``git`` that use ``main`` as the default branch name, which
led to errors when integrating with Overleaf (which uses ``master``).
- Revamped the way tests for the `showyourwork/showyourwork <https://github.com/showyourwork/showyourwork>`__
repo are run. Split tests into unit tests, local integration tests, and remote
integration tests. The first two can be executed on either the base repo or
any fork; the last one can only be executed on the base repo or upon the
``pull_request_target`` trigger from a PR, which occurs when a PR is labeled
``safe to test`` by a maintainer. This change will make contributing to
``showyourwork`` much easier going forward!
- Changed the syntax for specifying the ``showyourwork`` version number in the
``showyourwork.yml`` config file. Users should now specify whether the version
spec is a ``pip``-installable version, a ``path`` to a local installation,
or a ``ref`` on the GitHub repository (optionally on a given ``fork``).
The previous syntax (in which the version is provided as a string and the
code attempts to interpret it as one of the above options) is deprecated, but
will still be supported going forward. However, this
change is still **backwards-incompatible**, as versions of
``showyourwork`` prior to ``0.3.1`` will not be able to build repositories
that require versions greater than or equal to ``0.3.1`` (since previous
versions of the code will not be able to parse the new ``version`` mapping
syntax). Users can fix this by simply upgrading their local installation of
``showyourwork``.
- Removed built-in LaTeX class files for AAS journals, MNRAS, and A&A. Users
who upgrade to ``0.3.1`` (or later) must now include all necessary class files
and auxiliary TeX files in ``src/tex`` (and track them with ``git``). This
allows users to customize these files as needed and means we no longer have to
maintain them as they get updated by the journals.
- Removed the dependence on the ``marginnote`` package, which was causing issues
with some other packages that also defined a ``\marginnote`` command. The
margin link in the abstract now uses the built-in ``\marginpar``.
- Changelog: `v0.3.0...v0.3.1 <https://github.com/showyourwork/showyourwork/compare/v0.3.0...v0.3.1>`_

++++++++++++++++++

- Brand new release, featuring a complete re-write of the workflow. Below is
a list of the *major* changes:
- ``showyourwork!`` is now a pip-installable Python package. It is no longer
a git submodule. The ``showyourwork.yml`` file must now specify which version
of ``showyourwork`` to use.
- There is no longer a ``Makefile``. Articles should be built using the
``showyourwork`` command, which creates and activates a clean conda environment
containing ``Snakemake`` and all dependencies needed to run the pipeline for
each article. Users therefore no longer need to install ``Snakemake`` or ``mamba``
in the base environment.
- New articles can now be created using the ``showyourwork setup`` command rather than
via a GitHub repository template.
- The syntax for many of the settings in the ``showyourwork.yml`` config file has
changed, particularly for specifying Zenodo datasets.
- The directory structure for article repositories has changed slightly. Figure scripts
should now be placed in the ``src/scripts`` directory (used to be ``src/figures``).
The TeX files should now be placed in the ``src/tex`` directory (used to be ``src``).
Figure output files should now be generated in ``src/tex/figures`` (used to be ``src/figures``).
- To help with the transition to the new directory structure, new repositories include a
file ``src/scripts/paths.py`` that specifies absolute Pathlib paths to the main directories
in the repository.
- Figure scripts are no longer inferred from the ``\label`` command in LaTeX. Instead,
users should specify the script associated with a given figure using the new ``\script``
command.
- Added support for programmatically-generated files that can be included in the TeX
manuscript via the new ``\variable`` command.
- Users must now manually add ``\usepackage{showyourwork}`` to their LaTeX manuscript.
- Overhauled the way ``showyourwork`` integrates with Zenodo. Static datasets should now
be specified using their full DOI. Dynamic datasets are deprecated in favor of "cached"
datasets. These are intermediate results that get cached on Zenodo Sandbox alongside
a hash of the rules and all upstream dependencies used to generate them, making it
possible to automatically restore results from the cloud in a way that preserves the
full reproducibility of the workflow.
- Implemented (experimental) integration with Overleaf projects, allowing users to pull
changes to the manuscript and push changes to the figures.
- Drastically improved the command-line interface, suppressing most of the noise generated
by Snakemake in favor of succinct informational messages describing the build process.
All messages now get logged to files in ``.showyourwork/logs`` for easier debugging.
Similarly, improved error catching and added informational error messages for most of the failure
modes of the workflow.
- Several other tweaks, bugfixes, and improvements. Lots of changes to the back end to make
``showyourwork`` easier to develop, maintain, and extend!
- Changelog: `v0.2.3...v0.3.0 <https://github.com/showyourwork/showyourwork/compare/v0.2.3...v0.3.0>`_

++++++++++++++++++

- Bump ``jinja2`` version to fix issue with ``markupsafe``
- Changelog: `v0.2.2...v0.2.3 <https://github.com/showyourwork/showyourwork/compare/v0.2.2...v0.2.3>`_

++++++++++++++++++

- Tweaks to the logo (now an actual font!)
- Added option to exclude files from article cache on CI
- Fixed behavior of figures labeled with an asterisk (e.g., ``\label{fig*:...}``)
- Changelog: `v0.2.1...v0.2.2 <https://github.com/showyourwork/showyourwork/compare/v0.2.1...v0.2.2>`_