Wspieranie fortran-lang.org#

Fortran-lang.org jest programem o otwartym kodzie źródłowym a kontrybucje są mile widziane!

Wstęp#

W jaki sposób strona jest tworzona?

Treść strony jest pisana głównie jako połączenie plików Markdown (Myst), HTML i YAML (dane). Te źródła są następnie kompilowane do HTML, który tworzy ostateczną wersję strony.

Strona jest statyczna co znaczy, że po skompilowaniu, treść strony jest jednakowa dla wszystkich użytkowników, w przeciwieństwie do wielu stron, które są dynamiczne, co znaczy że mogą wyświetlać inną treść zależnie od użytkownika i danych przez niego wprowadzonych.

Statyczne części tworzące stronę zostały napisane w generatorze stron Sphinx Static a części dynamiczne w języku JavaScript.

Czy muszę znać HTML, żeby wesprzeć projekt?

Większość treści na stronie jest napisana w języku Markdown, prostym języku znaczników do formatowania tekstu. Nie przejmuj się jeżeli nie używałeś go wcześniej, bardzo łatwo się go nauczyć!

Jak strona jest tworzona?

Strona Fortran-lang używa Generatora stron statycznych Sphinx opartego na Pythonie do kompilowania plików RST, Markdown i HTML. Kontrybutorom zaleca się zainstalowanie Pythona na komputerze, tak aby można było wyświetlać podgląd zmian lokalnie. Nie jest to jednak obowiązkowe, ponieważ podgląd strony może zostać wygenerowany podczas żądania ściągnięcia (patrz poniżej). Sprawdź README.md, aby zobaczyć jak ustawić Sphinx i skompilować stronę.

Domyślna gałąź repozytorium Github zawiera tylko «kod źródłowy» strony, a nie jej końcowy skompilowany wynik; zautomatyzowana usługa kompiluje ten kod źródłowy za każdym razem, gdy nowa aktualizacja jest przesyłana i przechowuje skompilowany wynik w gałęzi gh-pages, która jest dostępna pod adresem https://fortran-lang.org.

Zatem, jako kontrybutor musisz tylko przesłać zmiany w kodzie źródłowym witryny, a nie skompilowanym wyniku, ponieważ jest on budowany automatycznie na podstawie kodu źródłowego gałęzi domyślnej.

Organizacja zadań#

Kontrybucje do strony są tworzone poprzez prośbę o ściągnięcie wysyłaną do repozytorium github: fortran-lang/webpage.

Organizacja zadań w tym celu przyjmuje następującą formę:

  1. Stwórz/zaktualizuj osobiste rozgałęzienie strony

  2. Stwórz nową gałąź w rozgałęzieniu

    • Nazwa gałęzi powinna treściwie opisywać twoją kontrybucję, np. naprawa-pisowni-strona-główna, zaktualizowanie-informacji-kompilatora

  3. Wykonaj swoje zmiany w gałęzi lokalnej

  4. Prześlij swoją zmodyfikowaną gałąź do twojego rozgałęzienia

    • n.p.git push --set-upstream origin naprawa-pisowni-strona-główna

  5. Stwórz prośbę o ściągnięcie na stronie fortran-lang/webpage ze swojego zmodyfikowanego rozgałęzienia

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.

Uwaga: Możesz kontynuować przesyłania zmian do swojej gałęzi po stworzeniu żądania o ściągnięcie - to żądanie zostanie odpowiednio zaktualizowane

Twoja prośba o ściągnięcie będzie oceniona przez innych członków społeczności, którzy mogą poprosić o wprowadzenie zmian. GitHub na swojej stronie zapewnia łatwy w obsłudze interfejs służący do zaakceptowania (lub odrzucenia) wszystkich sugestii oceniającego poprzez naciśnięcie jednego przycisku. To zapobiega manualnemu kopiowaniu sugestii do lokalnej kopii i przesyłaniu ich ponownie. Po naciśnięciu przycisku „Commit suggestion” wymagane jest zaktualizowanie lokalnej kopii na komputerze przy użyciu komendy git pull, aby przesłać więcej poprawek z komputera.

Po tym jak twoja prośba o ściągnięcie zostanie zaakceptowana, zazwyczaj przez dwóch lub więcej członków społeczności, zostanie ona przyłączona do domyślnej gałęzi strony przez opiekunów, po czym zostanie opublikowana na stronie fortran-lang.org.

W razie potrzeby, opiekunowie repozytorium mogą stworzyć publiczny podgląd zaproponowanych przez ciebie zmian, który będzie dostępny do obejrzenia pod adresem fortran-lang.org/pr/<pr_id>/, gdzie <pr_id> to numeryczny identyfikator twojego żądania ściągnięcia.

Dzięki temu oceniający mogą bezpośrednio zobaczyć wygenerowany rezultat twoich zmian.

Uwaga jeśli wyślesz kolejne zatwierdzenia (commit) do gałęzi żądania ściągnięcia, wymagane jest ponowne skompilowanie podglądu żądania ściągnięcia poprzez skomentowanie go sformułowaniem «#build_preview».

Po przyłączeniu żądania ściągnięcia i pomyślnym wyrenderowaniu go, kompilacja podglądu zostanie usunięta.

Uwaga jeśli link podglądu twojego żądania ściągnięcia nie działa lub nie aktualizuje się po ponownej kompilacji spróbuj dodać losowy parametr na końcu adresu URL np. https://fortran-lang.org/pr/98?v=2 - nazwa i wartość parametru nie mają znaczenia, ale używaj innej wartości dla każdej aktualizacji. To wymusi sieć dostarczania treści GitHub do dostarczenia ci zaktualizowanej wersji zamiast nieaktualnej wersji z pamięci podręcznej.

Przewodnik stylu#

Markdown#

  • Umieść fragmenty kodu w blokach kodu, oznaczone podwójnymi grawisami (```). Użyj stylu liniowego (`kod`) dla liniowych fragmentów kodu, słowach kluczowych języka programowania, nazw zmiennych oraz nazw plików.

  • Nie używaj więcej niż jednego zdania w wersie kodu źródłowego, a długie zdania dziel na wiele wierszy - jest to ważne, aby uniknąć dużych wykazów różnic oraz blokad w przeglądach kodu na githubie.

Pakiety ikon#

Ikony są prostym sposobem na poprawienie estetyki strony poprzez przełamywanie monotonicznych fragmentów tekstu oraz przykuwaniu uwagi na nagłówki i kluczowe informacje.

Trzy pakiety ikon dostępnych do użycia można znaleźć pod adresem fortran-lang.org:

Przykład: Font awesome

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

Przykład: Styl Sphinx wytyczne Myst

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

Aby przeglądać dostępne ikony odwiedź poszczególne strony.

Zawartość strony#

Czasem pomocnym jest wyświetlenie zawartości strony zawierającej hiperłącza w przypadku długich stron. Drzewo spisu treści strony zostało zautomatyzowane i wygeneruje spis treści dla bieżącej strony. Natomiast metodę generowania spisu treści dla całego katalogu na Fortran-lang.org jest następująca:

Dla stron typu Markdown:

dodaj wytyczne drzewa TOC w md na końcu strony indeksowej katalogu zawierającego nazwy wszystkich plików w tym katalogu.

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

Poradniki#

Wytyczne dotyczące treści miniksiążek.

Ogólny#

Użyj układu book.

Postępuj zgodnie z wytycznymi Markdown.

Styl kodu#

Używaj dwóch spacji do stworzenia wcięcia. Wcinaj zawartości jednostek, umieszczając wyrażenie contains na tym samym poziomie co module lub type. Spróbuj ograniczyć długość wersu do 90 znaków. Te praktyki powinny sprawić, że kod będzie bardziej przejrzysty i łatwiejszy do czytania na urządzeniach o mniejszej szerokości ekranu.

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

Każdy blok kodu powinien mieć podstawowy poziom wcięcia równy 0, nawet jeśli powinien być wcięty jeśli zostałby umieszczony w szerszym kontekście.

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

Unikaj pionowego wyrównywania :: oraz komentarzy wbudowanych w kod, ponieważ w większości przypadków utrudnia to konserwację i wydłuża długość wersów.

Jeśli blok kodu zawiera wersy, które nie są poprawne w języku Fortran, pozostaw je jako bloki kodu bez języka, aby uniknąć czerwonych podkreśleń składni.

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

Możesz pominąć odstępy w wyrażeniach, jeśli poprawia to czytelność kodu, jednak z reguły umieszczaj białe znaki wokół operatorów.

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

Zwykle dodawaj spację po przecinkach, wyjątkiem jest indeksowanie krótkich wartości oraz nazwy zmiennych.

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

Inne sytuacje oprócz prostego indeksowania, w których znaki białe mogą zostać pominięte:

  • Aliasing importów

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

  • Łączenie łańcuchów znaków

    print *, 'hello '//'world'

  • Uzyskiwanie dostępu do komponentów (atrybutów) typu pochodnego

    p%x
p%calc_something(a, b)

  • Obok = podczas przekazywania kluczowych argumentów

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

W komentarzach wbudowanych pierwszą literę pisz wielką literą, z wyjątkiem końcowych komentarzy wbudowanych, które składają się tylko z jednego słowa lub krótkiej frazy.

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

Te rekomendacje stylu kodu są podobne do tych przedstawionych w przewodniku stylu DFTB+.

Tekst#

W tytułach stron i sekcji używaj kapitalizacji tak jak w zdaniach (w przeciwieństwie do kapitalizowania wszystkich pierwszych liter słów).

Używaj emphasis (*emphasis*/_emphasis_, czyli zapisu kursywą) dla podkreślenia słów kluczowych/wyrażeń, które są pierwszy raz wprowadzane.

Unikaj używania strong(**strong**, czyli pogrubienia) w zwykłych akapitach, ponieważ styl ten używany jest w nagłówkach, do przyciągnięcia uwagi do przykładów (Przykład:), ostrzeżeń/tytułów na boku, itp.

W stosownych przypadkach skorzystaj z ostrzeżenia/przypisu na boku (note (uwaga), tip(wskazówka), important(ważne)).

  • Aby dodać note (notatka) do dokumentu md użyj:

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

  • Aby dodać tip (wskazówka) do dokumentu md użyj:

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

  • Aby dodać important (ważne) do dokumentu md użyj:

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

Preferuj użycie przecinka oksfordzkiego. Zazwyczaj sprawia, że sytuacja staje się bardziej jasna.

Fortran jest szybki, fajny i sławny.