Poradniki do mini-książek na fortran-lang.org

W tym poradniku wyjaśniono jak pisać samouczki w formie mini-książek dla sekcji Naucz się na stronie https://fortran-lang.org.

Ogólne wskazówki dotyczące współtworzenia strony https://fortran-lang.org znajdziesz w poradniki współtworzenia.

0. Mini-book formats

Mini-książki zaprojektowano tak, aby w większości samodzielnie wyjaśniały daną funkcję języka Fortran.

Istnieją dwa rodzaje formatów mini-książek:

• Jednostronicowy: cała zawartość napisana jest w jednym pliku typu Markdown i wyświetla się na pojedynczej stronie internetowej;

• Wielostronicowy: zawartość poradnika zapisana jest w wielu plikach typu Markdown i wyświetla się jako kolekcja stron internetowych.

Wybór formatu poradnika zależy od długości jego treści i planowanej struktury.

Przemyśl strukturę oraz spis treści, który zostanie utworzony:

• Jednostronicowe poradniki mają jeden poziom nawigacji: link do każdego nagłówka samouczka w spisie treści na stronie (spis treści po prawej stronie witryny).

• Wielostronicowe poradniki mają dwa poziomy nawigacji: link do każdego nagłówka samouczka w spisie treści na stronie (spis treści po prawej stronie witryny) oraz spis treści na pasku bocznym (spis treści po lewej stronie witryny pokazujący listę wszystkich stron w katalogu).

Jednostronicowe mini-książki są łatwiejsze w tworzeniu i powinny być używane do krótszych tematów lub poradników, które ostatecznie zostaną ujęte w bardziej obszernych wielostronicowych książkach.

Wielostronicowe książki rekomendowane są do bardziej obszernych poradników, gdzie jeden podtemat może być przedstawiony na jednej stronie.

Pozostała część tego poradniki podzielona jest na dwie części, po jednej dla jednostronicowych i wielostronicowych mini-książek.

1. Single-page mini-book

Kroki wymagane do opublikowania jednostronnicowej mini-książki:

• Utwórz nowy dokument typu Markdown w katalogu ./learn

• Napisz zawartość twojego poradnika

• Dodaj wpis do data/learning.yml dla twojej nowej mini-książki

• Otwórz żądanie ściągnięcia

1.1 Pisanie twojej mini-książki w pliku typu markdown

W przypadku mini-książek jednostronicowych twój poradnik będzie w całości zawarty w jednym dokumencie typu markdown.

Na początku stwórz nowy dokument typu markdown w katalogu ./learn/{{nazwa_miniksiążki}}/ z rozszerzeniem .md i krótką nazwą, która zwięźle opisuje temat twojego poradnika, np. ./learn/{{nazwa_miniksiążki}}/file_io.md.

Otwórz swój nowy dokument i dodaj wpis do spisu treści learn.md w następującym formacie:

:::{toctree}
:hidden:

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

Zamień {{book-filename}} na nazwę twojego pliku markdown z wyłączeniem rozszerzenia .md. Nie powinien się tam również znajdować ukośnik końcowy.

Przykład: nagłówek

:::{toctree}
:hidden:

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

NIE: link bezpośredni: /learn/file_io.md

NIE: link bezpośredni: /learn/file_io/

Teraz możesz uzupełnić resztę poradnika treścią napisaną w formacie markdown; kliknij Kramdown syntax, aby zobaczyć dokumentację implementacji plików markdown.

1.2 Tworzenie struktury za pomocą nagłówków

Nagłówki powinny być używane, aby nadać twojemu poradnikowi logiczną strukturę. Każdy nagłówek pojawi się w spisie treści wraz z hiperłączem.

W dokumentach markdown nagłówki mogą być zapisane jako:

# Heading level 1

## Heading level 2

### Heading level 3

#### Heading level 4

##### Heading level 5

###### Heading level 6

Uwaga: pamiętaj o umieszczeniu pustej linii przed nagłówkiem.

1.3 Dodaj swoją mini-książkę do strony Ucz się

Aby dodać swoją mini-książkę do strony Ucz się, musisz stworzyć nowy wpis w pliku data/learning.yml.

Otwórz ten plik i stwórz nowy wpis pod polem books: w następującym formacie:

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

To co wpiszesz pod polem title będzie nazwą twojego poradnika, która będzie się wyświetlać na stronie _Ucz się _ i z reguły powinna być taka sama jak pole title w twoim pliku markdown, jednak nie jest to wymagane.

Zawartość pola description (opis) jest także wyświetlana na stronie _Ucz się _ i powinna krótko streszczać zawartość twojego poradnika.

Pole category (kategoria) powinno odpowiadać jednej z kategorii wymienionych na górze pliku danych (pod polem categories:) i służy do grupowania poradników na stronie Ucz się.

Pole link powinno dokładnie odpowiadać polu permalink w twoim dokumencie markdown.

Przykład: wpis 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

Zapisz zmodyfikowany plik learning.yml, następnie uruchom fortran_package.py i skompiluj ponownie stronę na swoim komputerze lokalnym. Jeśli wszystko się powiodło, nowy link z tytułem twojego poradnika powinien pojawić się na stronie _Learn* (Ucz się).

Po ukończeniu swojej mini-książki i dodaniu wpisu do learning.yml, utwórz żądanie ściągnięcia na fortran-lang/webpage (zobacz KONTRYBUCJE).

2. Multi-page mini-books

Kroki wymagane do opublikowania wielostronicowej mini-książki:

• Utwórz nowy folder w katalogu ./learn/

• Utwórz plik index.md w twoim nowym folderze

• Napisz zawartość twojego poradnika w plikach typu markdown w twoim nowym folderze

• Dodaj wpis do data/learning.yml dla twojej nowej mini-książki

• Otwórz żądanie ściągnięcia

2.1 Utwórz nowy folder dla swojego poradnika

Utwórz nowy folder w katalogu ./learn/, z tytułem który będzie zwięźle opisywał treść twojego poradnika np../learn/coarrays/. Wszystkie strony twojej mini-książki będą znajdowały się w tym folderze.

Pierwsza strona twojej mini-książki powinna mieć nazwę index.md, dlatego utwórz nowy plik typu markdown o nazwie index.md w folderze twojej mini-książki oraz do twoich wszystkich plików markdown dodaj spis treści w następującym formacie:

:::{toctree}
:hidden:

file1
file2
:::

Na końcu nie powinno być żadnego ukośnika.

Przykład: spis treści dla index.md

:::{toctree}
:hidden:

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

NIE: link bezpośredni: /learn/coarrays/

Powinieneś wypełnić pozostałą część pliku index.md wprowadzeniem do twojego samouczka, które może zawierać: podsumowanie omawianych pojęć; wszelkie niezbędne wymogi; oraz odniesienia do innych powiązanych mini-książek lub przydatnych zasobów stron trzecich.

2.2 Dodaj strony do twojej mini-książki

Dla każdej nowej strony twojego poradnika stwórz nowy plik typu markdown w folderze twojej mini-książki.

Tak jak w przypadku jednostronicowych mini-książek, powinieneś używać nagłówków, aby nadać każdej stronie logiczną strukturę. Każdy nagłówek pojawi się w spisie treści na stronie.

2.3 Dodaj swoją mini-książkę do strony Ucz się

Aby dodać swoją mini-książkę do strony Ucz się, musisz stworzyć nowy wpis w pliku data/learning.yml.

Otwórz ten plik i stwórz nowy wpis pod polem books: w następującym formacie:

- 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}}

To co wpiszesz pod polem title będzie nazwą twojego poradnika, która będzie się wyświetlać na stronie _Ucz się _ i z reguły powinna być taka sama jak pole title w pliku markdown index.md, jednak nie jest to wymagane.

Zawartość pola description (opis) jest także wyświetlana na stronie _Ucz się _ i powinna krótko streszczać zawartość twojego poradnika.

Pole category (kategoria) powinno odpowiadać jednej z kategorii wymienionych na górze pliku danych (pod polem categories:) i służy do grupowania poradników na stronie Ucz się.

Pierwsze pole link powinno dokładnie odpowiadać polu permalink w pliku index.md.

Każde pole link w sekcji pages powinno dokładnie odpowiadać polu permalink na każdej kolejnej stronie miniksiążki.

Przykład: wpis 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

Zapisz zmodyfikowany plik learning.yml, a następnie uruchom fortranpackage.py i skompiluj ponownie stronę na swoim komputerze lokalnym. Jeśli wszystko się powiodło, nowy link z tytułem twojego poradnika powinien pojawić się na stronie _Learn (Ucz się).

Po ukończeniu swojej mini-książki i dodaniu wpisu do learning.yml, utwórz żądanie ściągnięcia na fortran-lang/fortran-lang.org (zobacz KONTRYBUCJE).