Tutoriales de mini-libros en fortran-lang.org#

Esta guía cubrirá cómo escribir tutoriales de minilibros para la sección Aprender de https://fortran-lang.org.

See contributing guidelines for general guidance on contributing to https://fortran-lang.org.

0. Mini-book formats#

Los minilibros están diseñados para ser en su mayoría tutoriales autónomos sobre una característica particular del lenguaje Fortran.

Hay dos tipos de formato de minilibro:

  • Single-page: all content is written within a single markdown file and displayed on a single webpage;

  • Multipágina: el contenido del tutorial se escribe en varios archivos Markdown y se muestra como una colección de páginas web.

La elección del tipo de libro depende de la extensión de su contenido y de cómo pretenda estructurarlo.

Considere la tabla de contenido que se producirá:

  • Los libros de una sola página tienen un nivel de navegación: un enlace para cada encabezado en el tutorial en inpage-toc (toc en el lado derecho de la página).

  • Los libros de varias páginas tienen dos niveles de navegación: un enlace para cada encabezado del tutorial en inpage-toc (toc en el lado derecho de la página) y sidebar-toc (toc en el lado izquierdo del página que muestra diferentes páginas en el directorio).

Los minilibros de una sola página son más simples de producir y deben usarse para temas breves o tutoriales breves que eventualmente se incluirán en un libro de varias páginas más completo.

Se recomiendan libros de varias páginas para tutoriales más completos que se pueden estructurar con un subtema por página.

El resto de esta guía se divide en dos secciones, una para los tipos de libros de una sola página y de varias páginas.

1. Single-page mini-book#

Los pasos necesarios para publicar un minilibro de una sola página son:

  • Create a new markdown document in the ./learn directory

  • Escriba el contenido de su tutorial

  • Agregue una entrada a data/learning.yml para su nuevo minilibro

  • Abrir una solicitud de integración

1.1 Writing your mini-book in markdown#

For single-page mini-books your tutorial will be entirely contained within a single markdown document.

First create a new markdown document in the ./learn/{{name_of_minibook}}/ directory with the .md file extension and a short name that concisely describes the topic of your tutorial, e.g. ./learn/{{name_of_minibook}}/file_io.md.

Open your new markdown file and append an entry in the toc of learn.md in the following format:

:::{toctree}
:hidden:

learn/quickstart/index
learn/best_practices/index
learn/os_setup/index
learn/building_programs/index
learn/intrinsics/index
learn/{{book-filename}}
:::

Replace {{book-filename}} with the filename of your markdown file but excluding the .md extension. There should also be no trailing slash.

Ejemplo: encabezado

:::{toctree}
:hidden:

learn/quickstart/index
learn/best_practices/index
learn/os_setup/index
learn/building_programs/index
learn/intrinsics/index
learn/file_io
:::

NOT: permalink: /learn/file_io.md

NOT: permalink: /learn/file_io/

You can now fill the rest of the file with your tutorial content written in markdown; see Kramdown syntax for documentation on the markdown implementation.

1.2 Estructurar tu minilibro con encabezados#

Debe usar encabezados para dividir su minilibro de una sola página en una estructura lógica. Cada encabezado aparecerá en la tabla de contenido con hipervínculos.

In markdown, headings can be written as:

# Heading level 1

## Heading level 2

### Heading level 3

#### Heading level 4

##### Heading level 5

###### Heading level 6

Nota: asegúrese de incluir una línea en blanco antes de su título.

1.3 Agregue su mini libro a la página de aprendizaje#

Para agregar su nuevo minilibro a la página Learn, debe agregar una nueva entrada en el archivo de datos data/learning.yml.

Abra este archivo y cree una nueva entrada en el campo books: con el siguiente formato:

- title: {{book-title}}
  description: {{book-description}}
  category: {{book-category}}
  link: /learn/{{book-filename}}

The title field is what will be displayed on the Learn page for your mini-book and should generally be the same as the title field in your markdown file, but this isn’t required.

El contenido del campo descripción también se muestra en la página Aprender y debe resumir brevemente el contenido del tutorial de su mini libro.

El campo categoría debe coincidir con una de las categorías enumeradas en la parte superior del archivo de datos (bajo el campo categorías:) y se usa para agrupar tutoriales en la página de aprendizaje.

The link field should exactly match the permalink field in your markdown document.

Ejemplo: entrada de libro learning.yml

- title: File input and output
  description: A tutorial on reading and writing files in Fortran
  category: Getting started
  link: /learn/file/file_io

Guarde el archivo de datos learning.yml modificado y ejecute fortran_package.py y reconstruya el sitio web en su máquina local para verificar los resultados. Si tiene éxito, debería aparecer un nuevo enlace en la página _Learn* con el título de su nuevo mini-libro.

Once you have completed your mini-book and added an entry to the learning.yml data file, open a pull request at https://github.com/fortran-lang/webpage (see CONTRIBUTING).

2. Multi-page mini-books#

The steps required for publishing a multi-page mini-book are:

  • Create a new folder in the ./learn/ directory

  • Create an index.md file in your new folder

  • Write your tutorial content in markdown files in your new folder

  • Agregue una entrada a data/learning.yml para su nuevo minilibro

  • Abrir una solicitud de integración

2.1 Create a new folder for your mini-book#

Create a new folder in the ./learn/ directory with a short name that concisely describes the topic of your tutorial, e.g. ./learn/coarrays/. All pages of your mini-book will be contained within this folder.

The first page of your mini-book should be called index.md, so create a new markdown file in your mini-book folder called index.md, and add a toc in the following format in all the markdown files:

:::{toctree}
:hidden:

file1
file2
:::

There should be no trailing slash.

Example: toc for index.md

:::{toctree}
:hidden:

learn/quickstart/index
learn/best_practices/index
learn/os_setup/index
learn/building_programs/index
learn/intrinsics/index
:::

NOT: permalink: /learn/coarrays/

you should populate the remainder of index.md with an introduction to your mini-book tutorial which may include: a summary of the concepts covered; any prerequisites; and any references to other related mini-books or useful third-party resources.

2.2 Add pages to your mini-book#

For each new page in your mini-book, create a new markdown file in your mini-book folder.

As with single-page mini-books, you should use headings to break-up each page into a logical structure. Each heading on the current page will show up in the inpage table-of-contents.

2.3 Add your mini-book to the Learn page#

Para agregar su nuevo minilibro a la página Learn, debe agregar una nueva entrada en el archivo de datos data/learning.yml.

Abra este archivo y cree una nueva entrada en el campo books: con el siguiente formato:

- title: {{book-title}}
  description: {{book-description}}
  category: {{book-category}}
  link: /learn/{{book-folder}}
  pages:
    - link: /learn/{{book-folder}}/{{page1-filename}}
    - link: /learn/{{book-folder}}/{{page2-filename}}
    - link: /learn/{{book-folder}}/{{page3-filename}}

The title field is what will be displayed on the Learn page for your mini-book and should generally be the same as the title field in your index.md markdown file, but this isn’t required.

El contenido del campo descripción también se muestra en la página Aprender y debe resumir brevemente el contenido del tutorial de su mini libro.

El campo categoría debe coincidir con una de las categorías enumeradas en la parte superior del archivo de datos (bajo el campo categorías:) y se usa para agrupar tutoriales en la página de aprendizaje.

The top-level link field should exactly match the permalink field in your index.md file.

Each link field under pages should exactly match the permalink field in each of your subsequent mini-book pages.

Ejemplo: entrada de libro learning.yml

- title: Parallel programming with Coarrays
  description: A tutorial on parallel programming using coarrays
  category: Parallel programming
  link: /learn/coarrays
  pages:
    - link: /learn/coarrays/background
    - link: /learn/coarrays/codimension
    - link: /learn/coarrays/examples

Save the modified learning.yml data file and run fortranpackage.py and rebuild the website on your local machine to check the results. If successful, a new link should appear on the _Learn page with the title of your new mini-book.

Once you have completed your mini-book and added an entry to the learning.yml data file, open a pull request at https://github.com/fortran-lang/fortran-lang.org (see CONTRIBUTING).