Contribuer à fortran-lang.org#

Ce site est en open source et vos contributions sont les bienvenues !

Introduction#

Comment est conçu le site ?

Le contenu du site est principalement écrit en Markdown (à la sauce Myst), HTML et YAML (pour les données). Ces sources sont compilées pour produire du HTML pur, qui est ce que vous voyez sur le site Web final.

Le site web est statique, ce qui signifie qu’une fois construit, le contenu du site est le même pour tous les utilisateurs, contrairement à de nombreux sites web qui sont dynamiques et peuvent servir un contenu différent en fonction de l’utilisateur et des données qu’il fournit.

Les composants structurels du site web sont écrits avec le générateur de site statique Sphinx pour les fonctionnalités statiques, et en JavaScript pour les fonctionnalités dynamiques.

Dois-je connaître le langage HTML pour contribuer ?

La majorité du contenu du site est rédigé en Markdown, un langage de balisage simple pour le formatage du texte. Ne vous inquiétez pas si vous ne l’avez jamais utilisé, il est très facile à prendre en main !

Comment ce site a-t-il été construit ?

Le site Fortran-lang utilise le générateur de site statique Sphinx, basé sur Python, pour compiler les fichiers RST, Markdown et HTML. Il est recommandé aux contributeurs d’installer Python sur leur ordinateur afin que les modifications puissent être prévisualisées localement, mais ce n’est pas obligatoire car les aperçus de site peuvent être générés pendant le processus de Pull Request (voir ci-dessous pour plus d’informations). Voir README.md pour savoir comment configurer Sphinx et construire le site.

Le branche par défaut du dépôt Github contient seulement le “code source” du site web, et non le résultat final compilé ; un service automatisé compile ce code source chaque fois qu’une mise à jour est poussée et stocke le résultat compilé sur la branche gh-pages qui est présentée sur https://fortran-lang.org.

Par conséquent, en tant que contributeur vous ne devez publier que les changements du code source du site et non le résultat compilé, car la compilation se fait automatiquement à partir du code source sur la branche par défaut.

Flux opérationnel#

Les contributions au site se font par demande de tirage sur le dépôt github : fortran-lang/webpage.

Le flux opérationnel (workflow) faisant cela prend la forme suivante :

  1. Créer / mettre à jour une duplication personnelle du site web

  2. Create a new branch in your fork

    • Le nom de la branche doit décrire votre contribution de façon concise, ex. fix-spelling-homepage, update-compiler-info

  3. Appliquer vos changements sur la branche locale

  4. Push your modified branch to your fork

    • ex. git push --set-upstream origin fix-spelling-homepage

  5. Créer une demande de tirage sur fortran-lang/webpage à partir de la branche modifiée de votre duplication

Note: Before opening a pull request you must build your changes locally using Sphinx (see README.md) to verify that your changes build correctly and render as you expect.

Note : Vous pouvez continuer de pousser des modifications sur la branche de votre duplication après avoir ouvert une demande de tirage - cette dernière sera mise à jour en conséquence

Your pull request will be reviewed by other members of the community who may request changes. GitHub provides an easy interface on its website to apply (or reject) any reviewer-suggested changes with a click of a button. This avoids having to manually copy suggestions to your local copy and push back again. If you use the « Commit suggestion » button, you will need to update the local copy on your computer using git pull if you intend to push more edits from your computer.

Once your pull request is approved, usually by at least two other community members, it will be merged into the webpage default branch by the maintainers at which point it will be published to the fortran-lang.org site.

If required, the repository maintainers can build a public preview of your proposed changes which will be available to view at fortran-lang.org/pr/<pr_id>/ where <pr_id> is the numeric identifier of your pull request.

This allows reviewers to directly view the generated result of your PR.

Note: if you push subsequent commits to your pull request branch, you must rebuild the pull request preview by commenting on the pull request with “#build_preview”.

After a pull request has been merged and successfully rendered, the workflows will delete the preview build.

Note: if your pull request preview link doesn’t work or doesn’t update after re-building, try adding a random parameter to the end of the URL, e.g. https://fortran-lang.org/pr/98?v=2 - the name and value of the parameter don’t matter, but use different values for each update. This will force the GitHub content delivery network to serve you an updated version instead of a cached version which is out-of-date.

Guide de style#

Markdown#

  • Place code excerpts in code blocks, denoted by back ticks (```). Use inline code style (`code`) for inline code excerpts, programming language keywords, variables names and file names.

  • Have no more than one sentence per source-code line, and break-up long sentences across multiples lines - this is important to avoid large git diffs and code review blocks on github.

Paquets d’icônes#

Icons are an easy way to improve page aesthetic by breaking-up otherwise monotonic text passages and drawing attention to headings or key information.

Three icon packs are available for use on fortran-lang.org:

Exemple : Font awesome

<i class="fas fa-info-circle"></i>

Example: Sphinx design Myst directives

{octicon}`book;1em;sd-text-info`

Visit the respective websites to browse available icons.

Page contents#

It is sometimes helpful to display hyperlinked page contents for lengthy pages. The page TOC tree has been automated and will generate the TOC of the current page. Whereas the method to generate TOC of the entire directory on Fortran-lang.org is:

Pour les pages en MD :

add the toc tree directive in md at the end of the index page of the directory with the names of the all files in that directory.

````{toctree}  
:hidden:
ARRAY_index 
````

Tutoriels#

Guidelines for mini-book content.

Général#

Use the book layout.

Suivez les directives Markdown.

Style de code#

Use two spaces for indentation, indenting bodies of units but keeping the contains statement at the same level as its module or type. Try to limit line length to 90 characters. These considerations should make the code more readable and easier to view on devices with smaller viewport widths.

module m
  implicit none
  private
  public :: a_t

  type :: a_t
    integer :: val
  contains
    procedure :: func
  end type a_t

contains

  subroutine func(self)
    class(a_t), intent(in) :: self
    if (self%val > 0) then
      print *, self%val
    end if
  end function func

end module m

Each code block should have a base indentation level of 0, even if it would be indented if put into a larger context.

integer :: i1  ! yes
  integer :: i2  ! no

Avoid vertically aligning :: and inline comments since this adds maintenance burden and pushes the line length in most cases.

If a code block contains lines that are not valid Fortran, leave it as a language-less code block to avoid the syntax highlighter’s red boxes.

module <module name>
...
end module <module name>

Feel free to omit spacing in expressions where it helps with readability, but generally include whitespace around operators.

y1 = a * b
y2 = a*b + c*d  ! instead of a * b + c * d
y3 = a**2 + 1
y4 = (a*b + c*d) / 2
s3 = s1 // s2

Generally add a space after commas, except when indexing with short index values or variables names.

a(:,1)
a2(1:10, 2:5)
b(i,j)
b2(long_i_name, long_j_name)
b3(i + 2, j)
call some_subroutine(a, b, an_option=.false.)
c = [1, 2, 3, 10]
d = [(i, i = 1, 10)]
do i = 1, 10
! ...

Other situations besides simple indexings where white space can be omitted:

  • Aliasing in imports

    use, intrinsic :: iso_c_binding, only: sp=>c_float, dp=>c_double

  • Concaténation de chaînes de caractères

    print *, 'hello '//'world'

  • Accessing components (attributes) of derived types

    p%x
p%calc_something(a, b)

  • Around = when passing keyword arguments

    call sr(a, b, c=3)
point = t_point(x=1., y=2.)
character(len=:), allocatable :: s

Capitalize the first letter for inline comments except for trailing inline comments that only consist of one word or a short phrase.

! Compute new values
y = m*x + b  ! meters

These code style recommendations are similar to those in the DFTB+ style guide.

Texte#

Use sentence case (as opposed to title case) for page and section titles.

Use emphasis (*emphasis*/_emphasis_, rendered as italic) for key words/phrases when they are first introduced, for emphasis, …

Avoid use of strong (**strong**, rendered as bold) within paragraphs, since bold style is used for headings, drawing attention to examples (Example:), admonition/aside titles, etc.

Make use of the admonition/aside (note, tip, important) where appropriate.

  • to add a note to md document use:

::::{note}
extra information, something that might appear in a footnote
:::::

  • to add a tip to md document use:

::::{tip}
information about best practices, practical tips
:::::

  • to add an important text to md document use:

::::{importrant}
warnings, things to avoid, etc.
:::::

Priviliégiez la virgule de série. Généralement cela rend les choses plus claires.

Fortran is fast, fun, and famed.