.. |showyourwork_help| raw:: html showyourwork --help .. |showyourwork_setup_help| raw:: html showyourwork setup --help .. |showyourwork_build_help| raw:: html showyourwork build --help .. |showyourwork_clean_help| raw:: html showyourwork clean --help .. |showyourwork_tarball_help| raw:: html showyourwork tarball --help .. |showyourwork_cache_help| raw:: html showyourwork cache --help Command line interface ====================== The |showyourwork| package implements a single command-line utility: ``showyourwork``, which allows users to set up, configure, and build their open source article. Below we describe this command and discuss its various subcommands. ``showyourwork`` ---------------- .. admonition:: |showyourwork_help| .. program-output:: showyourwork --help Running |showyourwork| (without any arguments) is a shortcut for ``showyourwork build`` (see :ref:`syw_build` below). .. _syw_setup: ``showyourwork setup`` ---------------------- .. admonition:: |showyourwork_setup_help| .. program-output:: showyourwork setup --help The ``setup`` subcommand sets up an open source article repository from scratch in the current working directory. This is an interactive command (unless you provide the ``--yes`` or ``--quiet`` options; see below). Let's step through what it does here. To set up a new open source article repository, run .. raw:: html
showyourwork setup $USER/$REPO
where you should replace ``$USER`` with your GitHub user name and
``$REPO`` with the name of your new article repository. For definiteness,
here we'll use my user name (``rodluger``) and we'll call our repository
``article``.
Step 1
^^^^^^
Running the ``setup`` command as above should bring up the following prompt:
.. raw:: html
Let's get you set up with a new repository. I'm going to create a folder called article in the current working directory. If you haven't done this yet, please visit https://github.com/new at this time and create an empty repository called rodluger/articleAs requested, if you haven't yet created the remote repository, go to `github.com/new
You didn't provide a caching service (via the --cache
command-line option), so I'm not going to set up remote caching for this repository.
.. _syw_setup_step2b:
Step 2B
^^^^^^^
If instead you passed the ``--cache`` flag, you'll see the following message:
.. raw:: html
You requested remote caching on Zenodo, so I'm going to create a deposit draft where intermediate results will be cached. Please make sure at this time that you have defined the ZENODO_TOKEN environment variable containing your API key for Zenodo. If you don't have one, visit https://zenodo.org/account/settings/applications/tokens/new to create a new personal access token with deposit:actions and deposit:write scopes and store it in the environment variable ZENODO_TOKEN. In order for this to work on GitHub Actions, you'll also have to visit https://github.com/tmp/tmp/settings/secrets/actions/new at this time to create a ZENODO_TOKEN secret with your API access token.Note that, in addition to the ``--cache`` flag, which enables caching on Zenodo, users may also provide the ``--sandbox`` flag, which switches the host to Zenodo Sandbox. Zenodo Sandbox behaves in exactly the same way as Zenodo, but it is explicitly meant as a test bed for dataset archiving. While deposits on Sandbox get assigned DOIs, they are no *actual* registered DOIs and have a limited lifespan. Sandbox is therefore a great choice for debugging and development; read more about it at :doc:`zenodo`. Note that if you choose the ``--sandbox`` option, you'll need a Zenodo Sandbox API token stored int the ``SANDBOX_TOKEN`` environment variable and GitHub Actions secret. .. warning:: Never commit your Zenodo API token (or any API token) directly to your repository! You can read more about GitHub secrets (and the security measures in place to prevent them from getting exposed to the outside world) at the `GitHub documentation
You didn't provide an Overleaf project id (via the --overleaf command-line
option), so I'm not going to set up Overleaf integration for this repository.
If you would like to set up integration with an Overleaf project (see :doc:`overleaf`),
hit ``Ctrl+C`` and run
.. code-block:: bash
showyourwork setup --overleaf=62150dd16134ef045f81d1c8
where you should replace ``62150dd16134ef045f81d1c8`` with the 24-character id
of a new (blank) Overleaf project. Once you create a new Overleaf project, you
can grab the id from the last bit of the project's URL. Note that |showyourwork|
requires the Overleaf project to be empty, otherwise it will refuse to set up
the integration. For more information on how this integration works, and what
to do if you have an existing Overleaf project you'd like to integrate with
|showyourwork|, please see :doc:`overleaf`.
Step 3B
^^^^^^^
If you specified the ``--overleaf`` option (see :ref:`syw_setup_step3a`),
you'll get the following message:
.. raw:: html
You provided an Overleaf project id, so I'm going to set up Overleaf integration for this repository. Please make sure at this time that you have defined the OVERLEAF_EMAIL and OVERLEAF_PASSWORD environment variables. In order for this to work on GitHub Actions, please go to https://github.com/tmp/tmp/settings/secrets/actions/new at this time and create OVERLEAF_EMAIL and OVERLEAF_PASSWORD secrets with your Overleaf credentials.To allow |showyourwork| to push to/pull from your Overleaf project, create the environment variables ``$OVERLEAF_EMAIL`` and ``$OVERLEAF_PASSWORD`` and populate them with your Overleaf email address and password, respectively; then re-run the setup command. Again, take care to never actually commit this information to your repository! Step 4 ^^^^^^ Finally, press any key to generate the repository. This will create a new folder in the current working directory with the same name as your repo (``article``, in the example above) and set up ``git`` tracking for it. Note that the first time you commit and push your changes to the GitHub repository, you'll have to specify the upstream branch as follows: .. code-block:: bash git push -u origin main .. _syw_build: ``showyourwork build`` ---------------------- .. admonition:: |showyourwork_build_help| .. program-output:: showyourwork build --help Run this command to build the article in the current working directory. Note that you must run this command from the top level of the repository (an error will be thrown otherwise). The command accepts any number of arguments, all of which are forwarded to ``snakemake``. By default, ``showyourwork`` passes the following arguments to ``snakemake``: .. code-block:: bash -c1 --use-conda --reason --cache Some of these, like the number of cores, can be overridden. For example, you may run .. code-block:: bash showyourwork build -c2 to run the workflow using two cores (see the `snakemake docs