You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: site/guidelines-authors.qmd
+81-45Lines changed: 81 additions & 45 deletions
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
2
title: Guidelines for authors
3
3
description: |
4
-
This page provides a step-by-step guide for authors to accompany them for formatting and submitting their paper to Computo.
4
+
Step-by-step guide to help authors format and submit their papers.
5
5
format:
6
6
html:
7
7
toc: true
@@ -14,30 +14,65 @@ lightbox: true
14
14
15
15
## A step-by-step guide to submitting a paper to Computo {#sec-guide}
16
16
17
-
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 freezing 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
+
Submissions to [Computo](https://computorg.github.io) require both scientific content (such as equations, code, figures, and data) and clear evidence that this content is reproducible. This is achieved through: i) a notebook system, ii) a virtual environment with frozen dependencies, and iii) continuous integration. If needed, large data files can be stored externally on platforms like[Zenodo](https://zenodo.org/) or [OSF](https://osf.io/).
18
18
19
-
A Computo submission is thus a Git(Hub) repository containing:
19
+
A Computo submission is therefore a Git(Hub) repository containing:
20
20
21
-
- the source files of the notebook (a quarto`.qmd` file + a BibTeX `.bib` file + some static files, _e.g._ figures or small `.csv` data tables);
22
-
- configuration files to set up the dependencies in a virtual environment;
23
-
- configuration files to set up the continuous integration rendering the final documents.
21
+
- the source files for the notebook (a Quarto`.qmd` file, a BibTeX `.bib` file, and any static files such as figures or small `.csv` data tables);
22
+
- configuration files to set up dependencies in a virtual environment;
23
+
- configuration files to enable continuous integration and render the final documents.
24
24
25
-
The [Computo](https://github.com/computorg) organization provides template repositories for [R](https://github.com/computorg/template-computo-R), [Python](https://github.com/computorg/template-computo-python) and [Julia](https://github.com/computorg/template-computo-julia) contributors. In the following sections, we detail step-by-step what authors have to do in order to format their paper for submission to Computo.
25
+
### Template repositories {#sec-templates}
26
+
27
+
The [Computo](https://github.com/computorg) organization provides template repositories for [R](https://github.com/computorg/template-computo-R), [Python](https://github.com/computorg/template-computo-python), and [Julia](https://github.com/computorg/template-computo-julia) contributors.
These templates provide a starting point for authors to format their contributions according to Computo's guidelines. They include the necessary files and configurations to set up a reproducible environment and continuous integration
26
63
27
64
### Setup a git repository {#sec-git}
28
65
29
-
Setup a new Github repository by browsing either the
30
-
[R](https://github.com/computorg/template-computo-R) or [Python](https://github.com/computorg/template-computo-python) or [Julia](https://github.com/computorg/template-computo-julia)
31
-
template repository and clicking the **"use this template"** button at the top of the page, as illustrated in @fig-template.
66
+
Create a new GitHub repository by navigating to the [R](https://github.com/computorg/template-computo-R), [Python](https://github.com/computorg/template-computo-python), or [Julia](https://github.com/computorg/template-computo-julia) template repository and clicking the **"Use this template"** button at the top of the page, as shown in @fig-template.
32
67
33
68
{#fig-template width="100%"}
34
69
35
70
::: {.callout-tip title="Branches"}
36
-
When you fork a GitHub repository, be it classic or template, GitHub asks if you want to fork all branches (there is a box called*Include all branches*). You only need to fork the main branch so you do not have to check that box.
71
+
When you fork a GitHub repository – whether it is a classic repository or a template – GitHub will ask if you want to include all branches (there is a box labeled*Include all branches*). You only need to fork the main branch, so you do not need to check that box.
37
72
:::
38
73
39
74
::: {.callout-caution title="Public repository"}
40
-
The paper will be automatically published online using GitHub pages. This is possible only with public repositories. Hence, when you initialize your repository from the template, make sure that the *Public* box is checked (the default) and not the *Private* one.
75
+
The paper will be automatically published online using GitHub pages. This is possible only with public repositories (which is the default behavior when you initialize your repository from this template). It is fine to keep your repository private during the writing phase. However, we ask you to set it public at the submission stage; so that the paper can be rendered and published online for the reviewers.
41
76
:::
42
77
43
78
In summary, before clicking on *Create repository*, you should have the options documented in @fig-clone-template.
@@ -50,35 +85,31 @@ You can use Gitlab for submitting to Computo. We will be giving more detailed su
50
85
51
86
### Local setup: clone, quarto, and computo extension {#sec-quarto}
52
87
53
-
You should first clone the repository on your local computer. From a terminal window, run:
88
+
First, clone the repository to your local computer. In a terminal, run:
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.
95
+
You need to have [Quarto](https://quarto.org/)and the [Computo extension](https://github.com/computorg/computo-quarto-extension)installed.
61
96
62
-
To install Quarto, you should refer to the instructions here: <https://quarto.org/docs/get-started/>.
97
+
- Install Quarto: follow instructions at <https://quarto.org/docs/get-started/>.
98
+
- Once Quarto is installed, open a terminal in your cloned repo folder and run:
63
99
64
-
Once Quarto is properly installed locally on your computer, you can install the Computo Quarto extension. To do this, open a terminal window in the folder of your local clone, and run the following command line:
If you are collaborating with others when writing your contributions, **each collaborator** needs to perform the same three steps:
73
-
74
-
- clone the repository,
75
-
- install Quarto,
76
-
- install the Computo Quarto extension by executing the above command.
107
+
If you are collaborating with others when writing your contributions, **each collaborator** needs to perform these same three steps (clone the repository, install Quarto and install the Computo Quarto extension).
77
108
:::
78
109
79
110
### Write your contribution {#sec-writing}
80
111
81
-
In the forked template, there are mainly two files you are expected to modify for writing your contribution: `template-computo-LANG.qmd` (where LANG is to be replaced with either R, python or julia) and `_quarto.yml`.
112
+
There are mainly two files you are expected to modify in your repository for writing your contribution: `template-computo-LANG.qmd` (where LANG is to be replaced with either R, Python or Julia) and `_quarto.yml`.
82
113
83
114
#### Main content of your contribution
84
115
@@ -101,7 +132,10 @@ To customise title, authors, date, abstract and so on, you should modify the `_q
101
132
102
133
```yml
103
134
project:
104
-
title: "template-computo-R"
135
+
type: default
136
+
render:
137
+
- template-computo-R.qmd
138
+
- README.qmd
105
139
106
140
title: "Template for contribution to Computo"
107
141
subtitle: "Example dedicated to `R` users"
@@ -135,12 +169,13 @@ github-user: computorg
135
169
repo: "template-computo-r"
136
170
draft: true # set to false once the build is running
137
171
published: false # will be set to true once accepted
172
+
license: CC-BY-4.0
138
173
format:
139
174
computo-html: default
140
175
computo-pdf: default
141
176
```
142
177
143
-
You can customize most of the entries in that file except `project:`, `published:` and `format:`. If your contribution is accepted for publication, the associate editors will modify parts of this file accordingly.
178
+
You can customize most of the entries in that file except `project:`, `published:`, `draft:`, `license:` and `format:`. If your contribution is accepted for publication, the associate editors will modify parts of this file accordingly.
144
179
145
180
### Setup dependencies {#sec-dependencies}
146
181
@@ -213,7 +248,7 @@ You can safely delete the `gh-pages` branch if you have one, as we don't need an
213
248
214
249
#### Handle external *system* dependencies
215
250
216
-
While you should have by now handled R, Python or Julia package dependencies using appropriate tools that register environments and version numbers, some of the packages your work depend upon might require external *system* dependencies that must be installed either when setting up the environment in the GitHub runner or when taking care of the paper rendering or in both cases. To take care of that, you can add and customize two scripts at the root of your repository. Specifically:
251
+
While R, Python, or Julia package dependencies should be managed using the appropriate environment tools, your project may also require external *system* dependencies (such as libraries or command-line tools). These must be installed on the GitHub runner during environment setup or rendering. To handle this, add and customize two scripts at the root of your repository:
217
252
218
253
- `setup-env-ci.sh` is meant to install system dependencies required to set up the environment in the GitHub runner. Here is an example of such a file taken from a published article:
219
254
@@ -237,13 +272,19 @@ Remember that the GitHub runner uses Linux Ubuntu and therefore software install
237
272
238
273
### Submit your manuscript {#sec-submitting}
239
274
240
-
Once you are done writing your contribution, recall that you can render it in both HTML and PDF by running `quarto render` from a terminal within the folder in which you cloned the Computo template.
275
+
Once you have finished writing your contribution, render it locally by running `quarto render` in your project folder. This will generate both HTML and PDF files if everything is set up correctly.
276
+
277
+
After confirming that the document builds successfully, push your changes to GitHub. The continuous integration workflow will automatically build and publish the HTML and PDF versions online.
241
278
242
-
If the Quarto rendering is successful locally (hence you get both HTML and PDF files), then, once you push the last modification to your repository on GitHub, the continuous integration and deployment scripts should automatically run and, if successful, the HTML version of your contribution will be published online, as well as a PDF version (see "Other format" at the end of the table of content of the rendered HTML).
279
+
::: {.callout-caution}
280
+
## Ignored files
281
+
Make sure to check and update the `.gitignore` file in your repository. In particular,
282
+
if you changed the name of some files in the repository (like the main `.qmd` file), make propagate this change to the `.gitignore` file in order to avoid pushing binary files to the repository (such as the PDF file).
283
+
:::
243
284
244
-
The PDF version should then be submitted to the [OpenReview](https://openreview.net/group?id=Computo) platform which will trigger the scientific review of the content of the PDF as well as the technical and reproducibility review from the repository.
285
+
To submit your manuscript for review, upload the generated PDF to the [OpenReview](https://openreview.net/group?id=Computo) platform. This will start both the scientific and reproducibility review processes.
245
286
246
-
You can find more details about the scientific reviewing process in the [dedicated page](/site/guidelines-reviewers.qmd) on this website (*Reviewers* tabs).
287
+
For more details about the review process, see the [guidelines for reviewers](/site/guidelines-reviewers.qmd).
247
288
248
289
### Accepted manuscript {#sec-acceptance}
249
290
@@ -261,42 +302,37 @@ A new page opens where you need to select *Specify an organization or username*
261
302
262
303
## Example papers {#sec-examples}
263
304
264
-
Authors can find example papers for each language that illustrate the expected content and some key features for formatting contributions as well as reminding some of the guidelines:
305
+
In addition to the template repositories that can serve as example papers [see @sec-templates], we provide more in-depth illustrations of the expected content and available features through mock contributions consisting of a complete reworking of the famous t-SNE article.
For other advanced examples, do not hesitate to explore the source code of any [paper already published in Computo](https://computo-journal.org/site/publications.html) to see how the template is used in practice. You can also access the source code of the example papers mentioned above by clicking on the `</> Source` button in the upper-right corner of the page as illustrated in @fig-template-source.
296
335
:::
297
-
:::
298
-
299
-
You can click above either on the screenshot or the URL to access the rendered version of each example paper. At any time you can then access the source code by clicking on the `</> Source` button in the upper-right corner of the page as illustrated in @fig-template-source.
300
336
301
337
{#fig-template-source width="100%"}
0 commit comments