Merge pull request #3 from computorg/minor_modif1

Minor modifications and improvements

Author: jchiquet

README.md

@@ -5,17 +5,19 @@
 
 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.
 
-Shows how to automatically setup and build the HTML and PDF outputs, ready to submit to our peer-review platform.
+It shows how to automatically setup and build the HTML and PDF outputs, ready to submit to our peer-review platform.
 
-Additional details can be found [in the template manuscript](https://computo.sfds.asso.fr/template-computo-python). 
+: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:
 
-  ## Process overview
+More information about submission and **guidelines for authors** can be found on the [dedicated page](https://computo.sfds.asso.fr/submit/).
+
+## Process overview
 
 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/) ). 
 
 A Computo submission is thus a git(hub) repository like this one containing 
 
-- 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)
+- 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)
 - configuration files to set up the dependencies in a virtual environment
 - configuration files to set up the continuous integration rendering the final documents
 
@@ -29,7 +31,7 @@ In this template, we focus on `Python` users and detail a solution based on
 
 ### Step 0: setup a git repository
 
-Use this repository as a template via the "use this template" button on the top of this page.
+Use this repository as a template via the **"use this template"** button on the top of this page.
 
 **Note**: _You can use Gitlab for submitting for Computo. We hope giving more support in the future._
 
@@ -48,10 +50,18 @@ Write your notebook as usual, [as demonstrated in the `template-computo-python.q
 
 **Note**: _Make sure that you are able to build your manuscript as a standard notebook on your system before proceeding to the next step._
 
+To build your document (both in PDF and HTML by default), you can run the command `quarto render`, e.g. for the template:
+
+```.bash
+quarto render template-computo-python.qmd # will render both to html and PDF
+```
+
 ### Step 3: setup dependencies with `venv`
 
 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.
 
+See [this page](https://computo.sfds.asso.fr/template-computo-python/#handle-python-dependencies-with-venv) for more details about `Python` dependency setup.
+
 ### Step 4: proof reproducibility
 
 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)

template-computo-python.qmd

@@ -52,19 +52,31 @@ This document, accompanied by the [customized GitHub repository](https://github.
 
 ## Setup a GitHub repository for preparing your submission
 
-You can start by clicking the "use this template" button, on the top of the page of the [github repository associated with this document](https://github.com/computorg/template-computo-python/). Of course, you can set your repository private during the preparation of your manuscript.
+You can start by clicking on the **"use this template"** button, on the top of the page of the [github repository associated with this document](https://github.com/computorg/template-computo-python/). Of course, you can set your repository private during the preparation of your manuscript.
 
 ## Quarto
 
+[Quarto](https://quarto.org/) is a versatile formatting system for authoring documents integrating markdown, LaTeX and code blocks interpreted either via Jupyter or Knitr (thus supporting Python, R and Julia). It relies on the [Pandoc](https://pandoc.org/MANUAL.html) document converter.
+
+## Requirements
+
 You need [quarto](https://quarto.org/docs/get-started/) installed on your system and the [Computo extension](https://github.com/computorg/computo-quarto-extension) to prepare your document. For the latter, once quarto is installed, run the following to install the extension in the current directory (it creates an `_extension` directory which is ignored by git thanks to `.gitignore` by default):
 
 ```.bash
 quarto add computorg/computo-quarto-extension
 ```
 
+[`Python`](https://www.python.org/) and [`Jupyter`](https://jupyter.org/install) must be installed on your computer.
+
+## Link with your usual tools
+
+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-python.qmd` file](https://github.com/computorg/template-computo-python/blob/main/template-computo-python.qmd) in the first cell, type "Raw", of the notebook]).
+
+**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._
+
 # Formatting
 
-This section covers basic formatting guidelines for [Quarto](https://quarto.org/), a versatile formatting system for authoring documents integrating markdown, LaTeX and code blocks interpreted either via Jupyter or Knitr (thus supporting Python, R or Julia). It relies on the [Pandoc](https://pandoc.org/MANUAL.html) document converter.
+This section covers basic formatting guidelines for quarto documents.
 
 To render a document, run `quarto render`. By default, both PDF and HTML documents are generated:
 
@@ -135,7 +147,7 @@ See @thm-slln.
 
 ## Python Code
 
-Quarto uses either Jupyter or knitr to render code chunks. This can be triggered in the yaml header. In this tutorial, we use `Jupyter` (`Python` and `Jupyter` must be installed on your computer).
+Quarto uses either Jupyter or knitr to render code chunks. This can be triggered in the yaml header. In this tutorial, we use `Jupyter`  (`Python` and `Jupyter` must be installed on your computer).
 
 ``` yaml
 ---
@@ -217,9 +229,12 @@ Advanced formatting features are possible and documented (including interactive
 ::: {.callout-warning}
 ## More information
 
-- [The Quarto web site](https://quarto.org) for comprehensive documentation.
+- [The Quarto web site](https://quarto.org) for comprehensive documentation, including:
+  + [Tutorial](https://quarto.org/docs/get-started/)
+  + [User guide](https://quarto.org/docs/guide/)
+  + [Options reference](https://quarto.org/docs/reference/)
 
-- [The template distributed with the Computo Quarto extension](https://computo.sfds.asso.fr/published-paper-tsne/), which uses such advanced features.
+- [The template distributed with the Computo Quarto extension](https://computo.sfds.asso.fr/computo-quarto-extension/), which uses such advanced features.
 
 - [Our mock version of the t-SNE paper](https://computo.sfds.asso.fr/published-paper-tsne/), a full and advanced example using Python and the Jupyter kernel.
 
@@ -300,8 +315,11 @@ Then, set the branch `gh-page` as the source of your github page, and trigger th
 
 [The build and deploy process of our Computo quarto extension](https://github.com/computorg/computo-quarto-extension/blob/main/.github/workflows/build.yml) shows how `miniconda` can be set used in place of `venv`. The main striking difference is the use of a `environment.yml` file in place of `requirements.txt`.
 
+## Data and large files
+
+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/).
+
 # References {.unnumbered}
 
 ::: {#refs}
 :::
-