make documentation more consistent

.github/workflows/reproduce.yml

@@ -11,8 +11,8 @@ jobs:
     env:
 #     LaTeX project name (basename of main file, e.g. main.tex -> main)
       LATEX_PROJECT: "main"
-#     Python scripts (glob patterns possible, e.g. "*.py" considers all .py files)
-      PYTHON_SCRIPT: "*.py"
+#     Code files (glob patterns possible, e.g. "*.py" considers all .py files)
+      CODE_FILES: "*.py"
 
     steps:
       - name: Set up Git repository
@@ -37,7 +37,7 @@ jobs:
 
       - name: Run Python scripts
         run: |
-          find . -name "${{ env.PYTHON_SCRIPT }}" -exec sh -c "grep '\- name\:.*' {} | python {}" \;
+          find . -name "${{ env.CODE_FILES }}" -exec sh -c "grep '\- name\:.*' {} | python {}" \;
 
       - name: Compile LaTeX document
         run: |

README.md

@@ -1,24 +1,20 @@
 # Re-Pro
 
-This repository helps you set up a reproducibility proof for your project. It's pretty simple, trust me.
+This repository helps you set up a reproducibility proof for your project. It's quite easy, trust me.
 
 ## About provable reproducibility
 
-There is an age-old saying in the Swiss army:
+How can scientists unmistakably know whether their results can be reproduced by other people? How can reviewers verify that a certain numerical experiment published in an article is correct? And how can collaborators quickly understand how to use the source code you have written for your project? As the age-old saying in the Swiss army goes:
 
-> Vertrauen ist gut; Kontrolle ist besser.
+> Vertrauen ist gut; Kontrolle ist besser. - Trust is good; control is better.
 
-> Trust is good; checking is better.
-
-How can scientists unmistakably know whether their results can be reproduced by other people? How can reviewers verify that a certain numerical experiment in an article is correct? And how can collaborators quickly understand how to use the source code you have written for your project?
-
-Provable reproducibility is an initiative, which pursues the goal of making results published in articles, theses, and software packages easy to reproduce and verify. No more ambiguity, data manipulation, cherry-picked parameters, and hand-crafted results. Every figure, plot, and table in a provably reproducible project can be unequivocally traced back to where it originated from.
+Provable reproducibility is an initiative, which pursues the goal of making results published in articles, theses, and software packages easier to reproduce and verify. No more ambiguity, data manipulation, cherry-picked parameters, and hand-crafted results. Every figure, plot, and table in a provably reproducible project can be unequivocally traced back to where it originated from.
 
 ## Quick start
 
-To add provable reproducibility to your GitHub repository, run the following command:
+To make your GitHub project provably reproducibile, run the following command:
 
-```[bash]
+```bash
 git pull https://github.com/FMatti/Re-Pro <preset>
 ```
 
@@ -34,13 +30,13 @@ You may choose from the following presets:
 In the `.github/workflows` directory, you may have to modify the `reproduce.yml` file as follows:
 
 - Change the `LATEX_PROJECT` variable to the name/path of your LaTeX main file (without the `.tex` extension)
-- Change the `PYTHON_SCRIPT` variable to the location of the Python script(s) you want to execute with the pipeline (glob patterns supported)
-- Change the Python package imports to the packages you use in your Python scripts
-- Change the LaTeX setup to the packages/compilers your project requires
+- Change the `CODE_FILES` variable to the location of the code file(s) you want to execute with the pipeline (glob patterns supported)
+- Change the package imports to the packages you depend on in your code
+- Change the LaTeX setup to the packages/compilers your project requires 
 
 Finally, commit and push the changes to GitHub:
 
-```[bash]
+```bash
 git commit --all -m "add reproducibility proof"
 git push
 ```
@@ -59,37 +55,46 @@ If something goes wrong, a red cross appears and you can click it and display mo
 
 [Failed image]
 
+Once you publish your GitHub repository, everyone can inspect your code and the steps used to generate your results.
+
+## Common issues
+
+Unless you are using some extraordinary dependencies or features in your project, your repository should now be configured for provable reproducibility. Some common problems which are encountered by people trying to set up a reproducibility proof are:
+
+- Ìf the branch you want to run the reproducibility proof on is not called `main`, you'll need to modify the `branches:` key at the top of the `reproduce.yml` file.
+- If your code files or LaTeX project is located in subdirectories, relative imports may not work any longer, hence you'll need to manually specify the working directory by adding  `
+  working-directory: [PATH]` below the commands which run the code.
+
 ## Example
 
-This repository serves as an example for how a provably reproducible project may look like. [Elaborate more in detail what is done]
+The `main` branch of this repository (which you are currently viewing) serves as an example for a provably reproducible project. It includes a
+
+- Python script called `plot.py` which downloads and saves a matrix (`matrix.npz`) from the internet, analyzes its principal components, and visualizes them in a plot which is saved as `plot.pgf`.
+
+- LaTeX project `main.tex` with a bibliography `bibliography.bib` which produces a PDF in which the generated plot `plot.pgf` is included.
 
 ## The Re-Pro badge
 
 The Re-Pro badge is the seal of reproducibility which can be displayed in a document. It certifies that a document was indeed produced based on the given commit.
 
 [Image of badge]
 
-## Extended setup
-
-Unless you are using some extraordinary dependencies or features in your project, your repository should now be configured for provable reproducibility.
+## Advanced usage
 
-- Non-default main branch -> change in `reproduce.yml`.
-- Add packages in TexLive installation
-- Commit to repository using
+### Commit and push changes to repository
 
-```[bash]
-...
+If you want to commit and push the generated changes from the reproducibility proof to your repository, add write-permissions to the build:
 
+```yaml
 jobs:
   build:
     permissions:
       contents: write
-...
 ```
-and subsequently adding the step
-```[bash]
-...
 
+Subsequently you can add the following step to your action (make sure to replace `[FILE]` by the filepaths of the files you want to be changed):
+
+```yaml
 - name: Commit and push generated files to repository
     run: |
         git config --global user.name "github-actions[bot]"
@@ -99,10 +104,10 @@ and subsequently adding the step
         git push
 ```
 
-## About PGF plots
+### Synchronizing GitHub repositories with Overleaf
 
-This example repository also serves as a demonstration of how matplotlib plots are to be exported and included in LaTeX projects. Any other way than using .pgf files for this purpose should be pursued as a criminal offence.
+Another advantage of tracking your code in a GitHub repository is that you can view and edit your project from Overleaf. The process for setting this up is described in the [Overleaf guide on GitHub Synchronisation](https://www.overleaf.com/learn/how-to/GitHub_Synchronization).
 
-## Opening GitHub repository with Overleaf
+### About PGF plots
 
-Another advantage of tracking your code in a GitHub repository is that you can view and edit your project from Overleaf. The process for setting this up is described in the [Overleaf guide on GitHub Synchronisation](https://www.overleaf.com/learn/how-to/GitHub_Synchronization).
+This example repository also serves as a demonstration of how matplotlib plots are to be exported and included in LaTeX projects. Any other way than using .pgf files for this purpose should be pursued as a criminal offence.