Zu fortran-lang.org beitragen#

Diese Website ist Open Source und Beiträge sind willkommen!

Einführung#

Wie ist die Website aufgebaut?

The content of the website is primarily written in a combination of Markdown (Myst flavoured), HTML and YAML (for data). This source is compiled to produce pure HTML which is what you see on the final website.

Die Website ist statisch, was bedeutet, dass der Inhalt der Website nach der Erstellung für alle Benutzer gleich ist; dies steht im Gegensatz zu vielen Websites, die dynamisch sind, d. h. sie können je nach Benutzer und den von ihm eingegebenen Daten unterschiedliche Inhalte anbieten.

Die strukturellen Komponenten der Website werden mit dem Sphinx Static Site Generator für statische Funktionen und mit JavaScript für dynamische Funktionen geschrieben.

Muss ich HTML können, um einen Beitrag zu leisten?

Der größte Teil des Inhalts der Website ist in Markdown geschrieben, einer einfachen Auszeichnungssprache zur Formatierung von Text - keine Sorge, wenn du dies noch nie benutzt hast, es ist sehr leicht zu erlernen!

Wie ist die Website aufgebaut?

Die Fortran-lang Seite nutzt den Python-basierten statischen Webseitengenerator Sphinx um die RST, Markdown und HTML Dateien zu kompilieren. Es ist für Mitwirkende empfehlenswert Python auf dem Rechner, den man zum Entwickeln verwendet, zu installieren, um sich Änderungen auch schon lokal vorher anschauen zu können, das ist allerdings nicht zwingend notwendig, da eine Seitenvorschau auch während des Pull Request Prozesses erstellt werden kann (dazu weiter unten mehr). Siehe auch README.md wie man Sphinx aufsetzt und damit die Seite baut.

Auf dem Standardzweig des GitHub Repos befindet sich stets nur der ‚Quellcode‘ der Webseite, nicht das endgültige kompilierte Ergebnis; ein automatisierter Dienst kompiliert diesen Quellcode bei jeder Aktualisierung und legt das Ergebnis auf den Zweig gh-pages, welcher dann auf https://fortran-lang.org angezeigt wird.

Deswegen müssen zum Mitwirken nur Änderungen an dem Quellcode der Seite hochgeladen werden und nicht die fertig kompilierten Ergebnisse, da diese automatisch aus dem Quellcode auf dem Standardzweig gebaut werden.

Arbeitsablauf#

Beiträge zur Website werden per Pull-Request an das Github-Repository übermittelt: fortran-lang/webpage.

Der Arbeitsablauf dafür sieht folgendermaßen aus:

  1. Erstelle/Aktualisiere einen persönlichen Fork der Webseite

  2. Erstelle einen neuen Zweig in Deinem Fork

    • Der Name des Zweigs sollte deinen Beitrag kurz und knapp zusammenfassen, z.B. fix-spelling-homepage, update-compiler-info

  3. Setze die Anpassungen auf deinem lokalen Ast um

  4. Pushe den modifizierten Zweig in den Fork

    • z.B. git push --set-upstream origin fix-spelling-homepage

  5. Erstelle einen pull-request auf der fortran-lang/webpage ausgehend von deinem modifizierten Zweig

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.

Hinweis: Du kannst auch nach der Öffnung eines pull-requests weiterhin Änderungen in deinen Fork-Zweig pushen - der pull-request wird sich dementsprechend anpassen

Dein pull-request wird von anderen Mitgliedern der Community gereviewed werden. Hierbei kann es sein, dass Änderungswünsche geäußert werden. Github stellt ein einfaches Interface auf der Website zur Verfügung um Vorschläge der Reviewer mittels simplen Knopfdruck zu akzeptieren oder abzulehnen. Dies erspart manuelles kopieren in deine lokale Kopie und erneutes pushen. Falls du den „Commit suggestion“-Button verwendest, ist es erforderlich die lokale Kopie auf deinem Rechner mittels git pull zu aktualisieren, falls du vorhast weitere Änderungen vorzunehmen.

Sobald dein pull-request akzeptiert wurde (im Normalfall sind zwei Mitglieder der Community erforderlich), wird er von den Maintainern in den Standard-Zweig der Website gemerged. Von diesem Zeitpunkt an sind die Änderungen auf der fortran-lang.org Seite einsehbar.

Falls es erforderlich sein sollte, können die Maintainer des Repositorys eine öffentliche Preview der vorgeschlagenen Änderungen erstellen. Diese kann auf fortran-lang.org/pr/<pr_id>/eingesehen werden. Hierbei ist <pr_id> die ID deines pull requests.

Dies ermöglicht den Reviewern direkt das Ergebnis deines pull-requests zu sehen.

Hinweis: falls du anschließend weitere Commits in den pull-request branch pushst, ist es erforderlich die pull-request-vorschau neu zu erstellen, indem du den pull-request mit ‚#build_preview‘ kommentierst.

Nachdem ein pull-request gemerged und erfolgreich gerendert wurde, wird im Rahmen des weiteren Workflows der Vorschaubuild gelöscht.

Hinweis: Falls dein pull-request-vorschau-link nicht funktionieren sollte oder nach einem Neu-Erstellen nicht aktualisiert werden sollte, versuche ans Ende der URL einen zufälligen Parameter, z.B. https://fortran-lang.org/pr/98?v=2 hinzuzufügen. Der Name und der Wert des Parameters ist hierbei irrelevant. Allerdings sollte mit jedem Update ein anderer Wert verwendet werden. Dieses Vorgehen erzwingt das GitHub content delivery network dazu dir eine aktualisierte Version anstatt einer veralteten Version aus dem Cache zu schicken.

Style Richtlinie#

Markdown#

  • Plaziere Code-Schnipsel in Code-Blöcke, gekennzeichnet durch „Rückwärtsanführungzeichen“ (```). Verwende den Inline-Code-Stil (`code`) für Inline-Code-Schnipsel, Keywords, Variablennamen und Dateinamen.

  • In jeder Quellcodezeile sollte nicht mehr als ein Satz sein und lange Sätze sollten über mehrere Zeilen aufgeteilt werden - Dies ist wichtig um große Unterschiede im Git und große Review Blöcke auf Github zu vermeiden.

Icon Packs#

Icons ermöglichen es auf einfache Weise die Seite ästhetischer zu gestalten, indem monotone Textpassagen durch die gezielte Lenkung der Aufmerksamkeit auf Überschriften oder Schlüsselinformationen unterbrochen werden.

Es sind drei Icon-Packs für die Verwendung auf fortran-lang.org verfügbar:

Beispiel: Font awesome

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

Beispiel: Sphinx design Myst directives

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

Besuche die jeweiligen Webseiten um die verfügbaren Icons zu durchsuchen.

Seiteninhalt#

Bei langen Seiten ist es manchmal hilfreich, Hyperlinks zum Seiteninhalt anzuzeigen. Der TOC-Tree der Seite wurde automatisiert und generiert das TOC der aktuellen Seite. Während die Methode zur Erzeugung des TOC des gesamten Verzeichnisses auf Fortran-lang.org ist hingegen:

Für Seiten in MD:

Ergänze die toc tree direktive im md am Ende der Index-Seite des Verzeichnisses mit den Namen aller Dateien in dem Verzeichnis.

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

Tutorials#

Ein Leitfaden für den Inhalt von Minibüchern.

Allgemeines#

Verwende das book Layout.

Folge den Markdown guidelines.

Code Style#

Verwende zwei Leerzeichen zum Einrücken. Rücke die Inhalte der Units ein, aber setze das contains Statement auf derselben Höhe wie module oder type. Versuche die Zeilenlänge auf 90 Zeichen zu begrenzen. Diese Überlegungen sollten dazu führen, dass der Code lesbarer und auf Geräten mit kleiner Bildschirmbreite leichter angezeigt werden kann.

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

Jeder code Block sollte zuerst auf Level 0 eingerückt werden. Dies gilt auch, wenn es in einen größeren Kontext integriert werden würde.

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

Vermeide das Ausrichten von :: sowie Inline-Kommentaren, da diese die Pflege erschwert und in den meisten Fällen die Zeilenlänge überschreitete.

Wenn ein Codeblock Zeilen enthält, die kein gültiges Fortran enthalten, lasse es in einem language-less code block um die roten Boxen des Syntax-Highlighters zu vermeiden.

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

In Ausdrücken können Leerzeichen weglassen werden, wenn es der Lesbarkeit dient, aber im Allgemeinen sollten Leerzeichen um Operatoren herum einfügt werden.

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

Generell sollten nach Kommas Leerzeichen eingefügt werden außer beim Indizieren mit kurzen Indexwerten oder Variablennamen.

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
! ...

Andere Situationen abseits von einfachem indizieren, in denen Leerzeichen weggelassen werden können:

  • Aliasing bei Importen

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

  • Concatenation von Strings

    print *, 'hello '//'world'

  • Zugriff auf Komponenten/Attributen von derived types

    p%x
p%calc_something(a, b)

  • Rund um das =, wenn Keyword-Argumente übergeben werden

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

In Inline-Kommentaren sollte der erste Buchstabe groß geschrieben werden, es sei denn es sind abschließende Kommentare, die nur aus einem Wort oder einer kurzen Phrase bestehen.

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

Diese Code-Style Empfehlungen sind ähnlich zu denen im the DFTB+ style guide.

Text#

Verwende für Seiten- und Abschnittsüberschriften Groß- und Kleinschreibung (im Gegensatz zu Titelüberschriften).

Verwende bei der ersten Verwendung Hervorhebungen (*Hervorhebung*/_Hervorhebung_, dargestellt in Kursiv) für Keywords/Phrasen zur Hervorhebung …

Vermeide die Verwendung von strong (**strong**, in fett dargestellt) innerhalb von Paragraphen, da die Fettschrift für Überschriften, zum Erregen von Aufmerksamkeit auf Beispiele (Beispiel:), Mahnung/Nebentitel, usw. verwendet wird.

Verwende Hinweise (Hinweis, Tip, Wichtig) wo es angemessen ist.

  • Um einen Hinweis in ein md Dokument hinzuzufügen, verwende:

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

  • Um einen Tip einem md-Dokument hinzuzfügen, verwende:

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

  • Um ein Wichtig-Text dem md-Dokument hinzuzufügen, verwende:

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

Bevorzuge das Oxford comma. Es macht Dinge üblicherweise klarer.

Fortran ist schnell, macht Spaß und ist bekannt.