Repository layout ================= If you created your repository from the `showyourwork template `_, it should have the following overall layout: .. raw:: html
Click on each of the files or folders in the directory tree above to read more about them. .. raw:: html .. _workflow: The ``.github/workflows/showyourwork.yml`` file *********************************************** This is the configuration file for the workflow that builds your article on GitHub Actions. It instructs GitHub Actions to build the article every time a commit is pushed to the remote: .. code-block:: yaml on: push: The workflow tells GitHub to checkout the repository: .. code-block:: yaml - name: Checkout uses: actions/checkout@v2 with: fetch-depth: 0 submodules: recursive and run the custom ``showyourwork-action`` to build the article: .. code-block:: yaml - name: Build the article PDF id: build uses: ./showyourwork/showyourwork-action You can add other steps to this workflow or configure the action settings (see :doc:`action`), but most users shouldn't have to tweak this file. Check out the `GitHub documentation `_ for more information on configuring workflows. .. _showyourwork: The ``showyourwork`` submodule ****************************** This is a `Git submodule `_ that contains the ``showyourwork`` workflow, which manages the entire build process for your article. You should not edit this submodule directly. However, you can update it to the latest version of ``showyourwork`` by running .. code-block:: bash git submodule update --remote in the top level of your repository, or switch to a specific version of the workflow (say ``v0.1.0``) by running .. code-block:: bash pushd showyourwork git fetch --all --tags git checkout tags/v0.1.0 popd again in the top level of your repository. Make sure to push your changes to the remote afterwards. Check out :doc:`update` for more information. .. _src: The ``src`` directory ********************* This directory contains the source code for building your article. This includes the LaTeX manuscript, the bibliography file, and the scripts and supplementary files needed to produce all of the article figures. Figure scripts and auxiliary code should be placed in the ``figures`` directory and (small) datasets and committed figures (if absolutely necessary!) should be placed in the ``static`` directory. See below for details. .. _figures: The ``figures`` directory ************************* This directory should contain all of the scripts needed to produce the figures in your article. The names of these scripts should match the figure labels in the manuscript file (see :doc:`here ` for details), although you can override this behavior by providing custom workflow rules (see :doc:`custom`). You can have other stuff in this directory as well (such as auxiliary scripts or procedurally-generated datasets). .. _matplotlibrc: The ``matplotlibrc`` config *************************** This is a ``matplotlib`` configuration file (see `the matplotlib docs `_). By default, it contains only a single instruction: .. code-block:: backend: agg which tells ``matplotlib`` to render figures using the non-interactive backend ``agg``. You can change this and add additional config options, but note that if the figures are generated using an interactive backend, this will likely cause the GitHub Action to fail! .. _bibliography: The ``bib.bib`` bibliography **************************** This is an optional LaTeX/BibTeX bibliography file. Feel free to delete or rename it if needed. .. _manuscript: The ``ms.tex`` manuscript ************************* This is your manuscript file. By default, it's a `AASTeX v6.3.1 `_ article file with a placeholder title, abstract, and introduction. Feel free to change the article class to whatever you'd like, although you may have to include (and commit) the ``.sty`` stylesheet if it's not in the standard TeXLive distribution. You can also import whatever packages you want in ``ms.tex`` -- the ``tectonic`` typesetting system will automatically download and install them when building your article. .. _gitignore: The ``.gitignore`` files ************************ The ``.gitignore`` files prevent you from committing certain kinds of files. You can add entries to these files, but you shouldn't have to remove any. In general, you should never commit figures (``.pdf``, ``.png``, ``.tiff``, etc), LaTeX temporaries (``.log``, ``.aux``, ``.blg``, etc), or any kind of output. In some cases, it might make sense to include one of these files (say, a ``.png`` photograph that can't be generated programatically from a script). To commit something that's disallowed by a ``.gitignore`` file, just use the ``-f`` or ``--force`` option when adding the file to ``git``. .. _gitmodules: The ``.gitmodules`` file ************************ The ``.gitmodules`` file simply tells ``git`` that the ``showyourwork`` directory is a submodule. You shouldn't have to change anything in here. .. _license: The ``LICENSE`` file ******************** The ``LICENSE`` included in your repository is by default the MIT open-source license. Feel free to change this to whatever license you prefer, although we strongly recommend you to keep everything open source and free for others to modify and adapt into their own work! .. _readme: The ``README.md`` file ********************** You should include a description of your repository here. Keep the badges at the top, as these provide easy access to the compiled article and the build logs. Feel free to remove or change the logo, though! .. _makefile: The ``Makefile`` **************** This is a standard Unix Makefile, enabling you to type ``make`` to build the article. You shouldn't have to edit anything in here. .. _snakefile: The ``Snakefile`` workflow ************************** The ``Snakefile`` contains all of the instructions on how to build your article from the files in your repository. If you're not familiar with the ``Snakemake`` workflow management system, read up on it `here `_. By default, the ``Snakefile`` should look something like this: .. code-block:: python # Import the showyourwork module module showyourwork: snakefile: "showyourwork/workflow/Snakefile" config: config # Use all default rules use rule * from showyourwork All this is doing is importing the ``showyourwork`` workflow (shipped within the ``git`` submodule in your repo) and then telling ``Snakemake`` to use all the rules in that workflow. You typically won't want to remove any of these lines, but feel free to add whatever you'd like to your ``Snakefile``. This might include rules to build custom figures, to download datasets, etc; see :doc:`custom`. Note, finally, that this file is written in a language that's a straightforward superset of Python, so any regular Python commands and syntax is valid in it. .. _environment: The ``environment.yml`` file **************************** The ``environment.yml`` file specifies all of the ``conda`` packages needed to build your article. You can read more about environment files `in the conda docs `_. By default, only the bare minimum specs are included (e.g., ``numpy`` and ``matplotlib``). Feel free to manually add to this list (noting that packages that can only be installed via ``pip`` should be placed in the ``pip`` section). It's recommended to either pin a specific version (i.e., ``matplotlib==3.3.4``) or specify a minimum version (i.e., ``matplotlib>=3.0.0``) for your packages. Just be aware that overconstrained requirements may break on other platforms (see `this post `_), so you should probably only pin the direct dependencies of your project. If you alread have a ``conda`` environment for your project, you can export these direct dependencies -- the ones that you explicitly installed in the enviornment -- by running .. code-block:: bash conda env export --from-history | grep -v "^prefix: " > environment.yml The ``grep`` command removes the line in the environment file with the absolute path to your ``conda`` environment, which probably won't be useful to anyone else running your code! .. _config: The ``showyourwork.yml`` config file ************************************ This is the `Snakemake config file `_ for ``showyourwork``, where you can customize several aspects of the build. Below is a list of all options along with their default values and a brief description of what they do: .. code-block:: yaml # Enable verbose output during the build process? verbose: true # Recognized figure extensions figexts: - pdf - png - eps - jpg - jpeg - gif - svg - tiff # Paths to be excluded from the arxiv tarball generated on GitHub Actions # Provide a list of files, one item per line preceded by a - ; glob # syntax allowed. Paths are relative to the root of the repo. arxiv_tarball_exclude: # Script dependencies. Each entry should be the name of a Python script # relative to the root of the repo. These entries, in turn, # should contain a list of dependencies, relative to the same folder. dependencies: # Zenodo metadata. This should be a list of dataset names relative to the # root of the repo. Each one should contain either a Zenodo ``id`` # for an existing deposit or instructions on how to generate and upload # a new deposit. Please see the documentation on `Custom workflows` for # more information. zenodo: