następujące komponenty i szablon są oparte na danych wejściowych wielu osób, które przyczyniły się do dyskusji „Create a README.szablon txt”. Aby mieć rozbudowany przykład, używamy przykładowego tekstu. Większość z nich pochodzi z modułu menu administracyjnego README.txt.

spis treści

TOCs są opcjonalne, ale doceniane w przypadku długich plików README.,

wprowadzenie

wprowadzenie (wymagane) składa się z krótkiego akapitu lub dwóch, które podsumowują cel i funkcję tego projektu. Wprowadzenie To może być takie samo jak pierwszy akapit na stronie projektu.

wprowadzenie powinno zawierać link do strony projektu i kolejki spraw. Jeśli projekt jest piaskownicy, te linki powinny przejść do piaskownicy do promocji.

wymagania

sekcja wymagania (wymagane) powinna jasno określać, czy ten projekt wymaga do działania czegokolwiek poza rdzeniem Drupala (Moduły, biblioteki itp.)., Wymień tutaj wszystkie wymagania, w tym te, które wynikają pośrednio z innego modułu, itp. Chodzi o to, aby poinformować użytkowników o tym, co jest wymagane, tak, że wszystko, czego potrzebują, mogą być zamówione i zawarte przed próbą instalacji modułu. Jeśli nie ma żadnych wymagań, napisz „Brak specjalnych wymagań”.

REQUIREMENTS------------This module requires no modules outside of Drupal core.

zalecane Moduły

ta opcjonalna sekcja zawiera listę modułów, które nie są wymagane, ale mogą zwiększyć użyteczność lub doświadczenie użytkownika projektu. Pamiętaj, aby opisać korzyści płynące z włączenia tych modułów.,

instalacja

sekcja instalacja (wymagane*) powinna jasno określać sposób instalacji modułu. Jeśli jednak kroki instalacji modułu postępują zgodnie ze standardowymi instrukcjami dla Drupal 8, Drupal 7, Drupal 6/5 lub motywu, nie wymyślaj koła na nowo — po prostu podaj link i szczegółowo wyjaśnij wszelkie kroki, które mogą odbiegać od tych kroków. Zwróć szczególną uwagę na integracje Drush. W przypadku dodania wielu poleceń Drush, rozważ dodanie sekcji dla Drush.

rozważ zastąpienie tej sekcji samodzielną instalacją.,plik txt, jeśli instrukcje instalacji są szczególnie złożone.

* – wymagane, chyba że oddzielna instalacja.txt jest dostarczany.

Drupal 7

Drupal 8

Konfiguracja

sekcja Konfiguracja (wymagana) jest niezbędna nawet wtedy, gdy wymagana jest niewielka konfiguracja. Użyj tej sekcji, aby wyświetlić specjalne uwagi dotyczące konfiguracji tego modułu – w tym między innymi uprawnienia. Ta sekcja jest szczególnie ważna, jeśli moduł wymaga dodatkowej konfiguracji poza interfejsem Drupala.,

Jeśli moduł ma niewielką lub żadną konfigurację, powinieneś użyć tego miejsca, aby wyjaśnić, w jaki sposób włączenie / wyłączenie modułu wpłynie na stronę.

CONFIGURATION------------- * Configure the user permissions in Administration " People " Permissions: - Use the administration pages and help (System module) The top-level administration categories require this permission to be accessible. The administration menu will be empty unless this permission is granted. - Access administration menu Users with this permission will see the administration menu at the top of each page. - Display Drupal links Users with this permission will receive links to drupal.org issue queues for all enabled contributed modules. The issue queue links appear under the administration menu icon. * Customize the menu settings in Administration " Configuration and modules " Administration " Administration menu. * To prevent administrative menu items from appearing twice, you may hide the "Management" menu block.

lub

Rozwiązywanie problemów& FAQ

te sekcje są opcjonalne. Jeśli są obecne, powinny odpowiadać na pytania, które są często zadawane w kolejce spraw (pozwoli to zaoszczędzić czas w przyszłości). Zarys typowych problemów, które napotykają ludzie wraz z rozwiązaniami (linki są w porządku, jeśli kroki są długie, ale często pomocne jest przedstawienie podsumowania, ponieważ linki czasami stają się nieświeże).,

opiekunowie

Ta sekcja jest opcjonalna i powinna zastąpić wszystkie istniejące samodzielne opiekunowie.plik txt.

zaawansowana pomoc

zaawansowana pomoc wyświetli plik README na ekranie, jeśli jest włączony.

wszystko o Markdown

w okresie istnienia projektu Drupal nigdy nie było wyraźnego konsensusu co do tego, jak powinien wyglądać plik README, a w rezultacie istnieje wiele różnych stylów (patrz linki poniżej). Jednak w nowych projektach preferujemy format opisany na tej stronie lub format rozpoznawany przez moduł filtra Markdown., Jeśli używasz Markdown, Twój plik powinien mieć nazwę README.md (i używać poprawnej składni Markdown), w przeciwnym razie powinien być nazwany README.txt.

Wskazówki dotyczące szybkiego formatowania

oto podsumowanie preferowanego formatu README.txt:

• nagłówki pisane wielkimi literami.
• nagłówki podkreślone===/--- do długości nagłówka, po którym następuje pusta linia.
• dwie linijki przed nagłówkami (z wyjątkiem pierwszej).
• kule oznaczone gwiazdkami ( * ) z wiszącymi wcięciami.
• listy numerowane miały 4 spacje.,
• lista zawiera 1 spację.
• tekst ręcznie zawijany w ok.

przykładowe pliki readme

niektóre przykładowe pliki README:

• Morbus' README.styl txt (który najbardziej odpowiada stylowi Drupal core).
• bułka tarta README.md (który używa tego szablonu)