|
3 | 3 |
|
4 | 4 | [](https://github.com/computorg/template-computo-python/actions/workflows/build.yml) |
5 | 5 |
|
6 | | -Documentation and sample of a simple `Python`-based submission for the [Computo journal](https://computorg.github.io), using our Quarto-based template and `venv` for handling dependencies. |
| 6 | +Documentation and sample of a simple `Python`-based submission for the [Computo journal](https://computo-journal.org), using our Quarto-based template and `micromamba` for handling dependencies (`pip` is also supported). |
7 | 7 |
|
8 | 8 | It shows how to automatically setup and build the HTML and PDF outputs, ready to submit to our peer-review platform. |
9 | 9 |
|
10 | | -:warning: **All important information about writing and preparing an article to be submitted to Computo, and related technicalities** are detailed [in the template manuscript](https://computo.sfds.asso.fr/template-computo-python). :warning: |
| 10 | +:warning: **All important information about writing and preparing an article to be submitted to Computo, and related technicalities** are detailed [in the guidelines for authors](https://computo-journal.org/site/guidelines-authors.html). :warning: |
11 | 11 |
|
12 | | -More information about submission and **guidelines for authors** can be found on the [dedicated page](https://computo.sfds.asso.fr/submit/). |
13 | | - |
14 | | -## Process overview |
15 | | - |
16 | | -Submissions to [Computo](https://computorg.github.io) require both scientific content (typically equations, codes and figures, data) and a proof that this content is reproducible. This is achieved by means of i) a notebook system, ii) a virtual environment fixing the dependencies and iii) continuous integration (plus, if needed, an external website to store large data files such a [Zenodo](https://zenodo.org/) or [OSF](https://osf.io/) ). |
17 | | - |
18 | | -A Computo submission is thus a git(hub) repository like this one containing |
19 | | - |
20 | | -- the source files of the notebook (a quarto `.qmd` file + a BibTeX `.bib` file + some statics files, _e.g._ figures or small `.csv` data tables) |
21 | | -- configuration files to set up the dependencies in a virtual environment |
22 | | -- configuration files to set up the continuous integration rendering the final documents |
23 | | - |
24 | | -In this template, we focus on `Python` users and detail a solution based on |
25 | | - |
26 | | -- The `Jupyter` kernel of Quarto for rendering the document, |
27 | | -- The `venv` Python built system for setting the virtual environment, |
28 | | -- Github actions for handling the continuous integration. |
29 | | - |
30 | | -## Step-by-step procedure |
31 | | - |
32 | | -### Step 0: setup a git repository |
33 | | - |
34 | | -Use this repository as a template via the **"use this template"** button on the top of this page. |
35 | | - |
36 | | -**Note**: _You can use Gitlab for submitting for Computo. We hope giving more support in the future._ |
37 | | - |
38 | | -### Step 1. setup Quarto and Computo extension on your system |
39 | | - |
40 | | -You need [quarto](https://quarto.org/) installed on your computer, as well as the [Computo extension](https://github.com/computorg/computo-quarto-extension) to prepare your document. |
41 | | -The latter can be installed as follows: |
42 | | - |
43 | | -```.bash |
44 | | -quarto add computorg/computo-quarto-extension |
45 | | -``` |
46 | | - |
47 | | -### Step 2. write your contribution |
48 | | - |
49 | | -Write your notebook as usual, [as demonstrated in the `template-computo-python.qmd` sample](https://computorg.github.io/template-computo-python/). |
50 | | - |
51 | | -**Note**: _Make sure that you are able to build your manuscript as a standard notebook on your system before proceeding to the next step._ |
52 | | - |
53 | | -To build your document (both in PDF and HTML by default), you can run the command `quarto render`, e.g. for the template: |
54 | | - |
55 | | -```.bash |
56 | | -quarto render template-computo-python.qmd # will render both to html and PDF |
57 | | -``` |
58 | | - |
59 | | -### Step 3: setup dependencies with `venv` |
60 | | - |
61 | | -Use the [`venv` package manager](https://cewing.github.io/training.python_web/html/presentations/venv_intro.html) to setup a reproducible environment handling your `Python` dependencies. |
62 | | - |
63 | | -See [this page](https://computo.sfds.asso.fr/template-computo-python/#handle-python-dependencies-with-venv) for more details about `Python` dependency setup. |
64 | | - |
65 | | -### Step 4: proof reproducibility |
66 | | - |
67 | | -Put everything together and check that your work is indeed reproducible. To this end, you need to rely on a github action, whose default is pre-configured and found here: [.github/workflows/build.yml](https://github.com/computorg/template-computo-R/blob/main/.github/workflows/build_n_publish.yml) |
68 | | - |
69 | | -This action will |
70 | | - |
71 | | -1. Check out repository on the ubuntu-latest machine |
72 | | -2. Install quarto and dependencies, including the Computo extension for Quarto |
73 | | -4. Install Python dependencies with `pip` and `venv`, using your `requirements.txt` file |
74 | | -5. Render your .qmd file and Publish the results on a gh-page (both HTML and PDF) |
75 | | - |
76 | | -**Note**: _Gitlab CI can be used to obtained similar results._ |
77 | | - |
78 | | -### Step 5. submit |
79 | | - |
80 | | -Once step 4 is successful, you should end up with an HTML version published as a gh-page, as well as a PDF version (see "Other format" at the end of the table of content of the rendered HTML). This PDF version can be submitted to the [OpenReview platform](https://openreview.net/group?id=Computo). |
0 commit comments