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
[](https://github.com/computorg/template-computo-julia/actions/workflows/build.yml)
Documentation and sample of a simple `Julia`-based submission for the [Computo journal](https://computo-journal.org), using our Quarto-based template and Julia github-action for handling dependencies.
20
+
### Authors
7
21
8
-
It shows how to automatically setup and build the HTML and PDF outputs, ready to submit to our peer-review platform.
22
+
-[Jane Doe](https://janedoe.someplace.themoon.org) (Name of Affiliation
23
+
one)
24
+
-[John Doe](https://johndoe.someplace.themoon.org) (Name of
25
+
Afficiliation two)
9
26
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:
27
+
### Abstract
11
28
29
+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur
[](https://github.com/{{< meta github-user >}}/{{< meta repo >}}/actions/workflows/build.yml)
Template for preparing a submission to Computo, using the [quarto journal extension](https://github.com/computorg/computo-quarto-extension), the Julia 1-10 Jupyter kernel and the Julia `Pkg` manager to set-up the dependencies.
31
+
32
+
For a detailed, step-by-step guide on preparing your article, setting up the continuous integration and submitting it to Computo, please consult the [guidelines for authors](https://computo-journal.org/site/guidelines-authors.html).
33
+
abstract: >+
34
+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur posuere vestibulum facilisis. Aenean pretium orci augue, quis lobortis libero accumsan eu. Nam mollis lorem sit amet pellentesque ullamcorper. Curabitur lobortis libero eget malesuada vestibulum. Nam nec nibh massa. Pellentesque porttitor cursus tellus. Mauris urna erat, rhoncus sed faucibus sit amet, venenatis eu ipsum.
35
+
keywords: [key1, key2, key3]
36
+
bibliography: references.bib
37
+
github-user: computorg
38
+
repo: "template-computo-julia"
39
+
draft: true # set to false once the build is running
40
+
published: false # will be set to true once accepted
This document provides a template based on the [`quarto`](https://quarto.org/) system for contributions to Computo, using the [`quarto journal extension`](https://github.com/computorg/computo-quarto-extension), the Julia 1-10 Jupyter and the Julia `Pkg` manager to set-up the dependencies.
26
-
abstract: >+
27
-
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur posuere vestibulum facilisis. Aenean pretium orci augue, quis lobortis libero accumsan eu. Nam mollis lorem sit amet pellentesque ullamcorper. Curabitur lobortis libero eget malesuada vestibulum. Nam nec nibh massa. Pellentesque porttitor cursus tellus. Mauris urna erat, rhoncus sed faucibus sit amet, venenatis eu ipsum.
28
-
keywords: [key1, key2, key3]
29
-
bibliography: references.bib
30
-
github-user: computorg
31
-
repo: "template-computo-julia"
32
-
draft: true # set to false once the build is running
33
-
published: false # will be set to true once accepted
34
-
format:
35
-
computo-html: default
36
-
computo-pdf: default
37
-
jupyter: julia-1.10
38
-
---
39
1
40
2
# Introduction
41
3
42
4
## About this document
43
5
44
-
This document, accompanied with the [hopefully finely tuned git repos](https://github.com/computorg/template-computo-julia/), provides a template for writing contributions to **Computo**[@computo]. We show how `Julia` code can be included and how the repository can be set up for triggering github actions for rendering the document, with dependencies handled by the built-in `Pkg` manager.
45
-
46
-
## Setup a github repository for preparing your submission
6
+
This document, accompanied with the [hopefully finely tuned git repos](https://github.com/computorg/template-computo-julia/), provides a template for writing contributions to **Computo**[@computo].
47
7
48
-
You can start by clicking the "use this template" button, on the top of the page of the [github repository associated to this document](https://github.com/computorg/template-computo-julia/). Of course, you can set your repository private during the preparation of your manuscript.
8
+
::: {.callout-tip}
9
+
## Note
10
+
This document provides only the key formatting principles. For a detailed, step-by-step guide on preparing your article and submitting it to Computo, please consult the [guidelines for authors](https://computo-journal.org/site/guidelines-authors.html).
11
+
:::
49
12
50
13
## Quarto
51
14
@@ -61,20 +24,14 @@ quarto add computorg/computo-quarto-extension
61
24
62
25
[`Julia`](https://julialang.org/) and [`Jupyter`](https://jupyter.org/install) must be installed on your computer.
63
26
64
-
## Link with your usual tools
65
-
66
-
Quarto is expecting a `.qmd` markdown file, but will also works with a standard [Jupyter notebook](https://quarto.org/docs/get-started/hello/jupyter.html) file if you are used to it (it will just require to add the proper YAML metadata^[the same metadata as in the [`template-computo-julia.qmd` file](https://github.com/computorg/template-computo-julia/blob/main/template-computo-julia.qmd) in the first cell, type "Raw", of the notebook]).
67
-
68
-
**Note**: _More advanced Jupyter-related functionality like Myst/Jupyter book are not supported in this Quarto setup. The markdown syntax inside the Jupyter notebook should follow the Quarto syntax (c.f. [below](#formatting)). If you are more comfortable with using Myst/Jupyter book, we provide a [specific template](https://github.com/computorg/template-computo-myst) but it will requires more formatting work for Computo editorial team, thus highly encourage authors to use the Quarto templates._
69
-
70
27
# Formatting
71
28
72
29
This section covers basic formatting guidelines for quarto documents.
73
30
74
31
To render a document, run `quarto render`. By default, both PDF and HTML documents are generated:
75
32
76
33
```.bash
77
-
quarto render template-computo-julia.qmd # will render both to html and PDF
34
+
quarto render # will render both to html and PDF
78
35
```
79
36
80
37
::: {.callout-tip}
@@ -237,43 +194,6 @@ Advanced formatting features are possible and documented (including interactive
237
194
238
195
:::
239
196
240
-
# Finalize your submission
241
-
242
-
## Handle `Julia` dependencies with `Pkg`
243
-
244
-
To make your work reproducible, you need to fix the packages and environment used to run your analysis. In `Julia`, the built-in `Pkg` package manager is a method of choice. [https://towardsdatascience.com/how-to-setup-project-environments-in-julia-ec8ae73afe9c](This simple tutorial shows how to set up a project).
245
-
246
-
In this tutorial, we simply need to add the `Plots` library and its dependencies. It is important that you also add `IJulia` to your project, since it is a required dependency for quarto to correclty render your document via Jupyter.
247
-
248
-
Once added via the `Pkg` manager of Julia (`add Plots; add IJulia`), the files `Project.toml` and `Manifest.toml` in the current project directory contains all the information required.
249
-
250
-
## Continuous integration
251
-
252
-
The repository associated with this template is pre-configure to trigger an action on push that performs the following:
253
-
254
-
1. Check out repository on the `ubuntu-latest` machine
255
-
2. Install quarto and dependencies, including the Computo extension
256
-
3. Install Julia (1.10) and dependencies based on the files `Project.toml` and `Manifest.toml`
257
-
4. Render your .qmd file and Publish the results on a gh-page (both HTML and PDF)
258
-
259
-
The file [.github/workflows/build_n_publish.yml](https://github.com/computorg/template-computo-python/blob/main/.github/workflows/build_n_publish.yml) is largely inspired from [this file](https://quarto.org/docs/publishing/github-pages.html#example-jupyter-with-venv).
260
-
261
-
Once this is successful, you are ready to submit your manuscript to the [Computo submission platform](https://computo.scholasticahq.com/).
262
-
263
-
::: {.callout-warning}
264
-
The first time, you possibly need to create the branch for the action to work. This can be done by running the following command from your computer, in your git repository:
265
-
266
-
```.bash
267
-
quarto publish gh-pages
268
-
```
269
-
270
-
Then, set the branch `gh-page` as the source of your github page, and trigger the action to check that everything works fine.
271
-
:::
272
-
273
-
## Data and large files
274
-
275
-
If your submission materials contain files larger than 50MB, **especially data files**, they won’t fit on a git repository as is. For this reason, we encourage you to put your data or any materials you deem necessary on an external “open data” centered repository hub such a [Zenodo](https://zenodo.org/) or [OSF](https://osf.io/).
0 commit comments