PAKIETY R ZARZĄDZANIE TESTOWANIE DOKUMENTACJA I UDOSTĘPNIANIE KODU

SPIS TREŚCI

Przedmowa

Część I. Rozpoczęcie pracy

1. Cała gra
Wczytywanie pakietu devtools i związanych z nim narzędzi
Przykładowy pakiet: regexcite
Podgląd gotowego produktu
create_package()
use_git()
Tworzenie pierwszej funkcji
use_r()
load_all()
Przekazanie funkcji strsplit1() do repozytorium
check()
Edycja pliku DESCRIPTION
use_mit_license()
document()
Zmiany w pliku NAMESPACE
Ponowne wywołanie check()
install()
use_testthat()
use_package()
use_github()
use_readme_rmd()
Koniec pracy: check() i install()
Podsumowanie
2. Konfiguracja systemu
devtools, usethis i Ty
Osobista konfiguracja podstawowa
Zestaw narzędzi do tworzenia pakietów R
Windows
macOS
Linux
Weryfikacja poprawności systemu
3. Stan i struktura pakietu
Stany pakietu
Kod źródłowy pakietu
Pakiet umieszczony w paczce
.Rbuildignore
Pakiet binarny
Pakiet zainstalowany
Pakiet w pamięci
Biblioteki pakietu
4. Podstawy sposobu pracy
Tworzenie pakietu
Analiza istniejącego środowiska
Nadanie nazwy pakietowi
Tworzenie pakietu
Dlaczego należy korzystać z wywołania create_package()?
Projekty RStudio
Zalety używania projektów RStudio
Tworzenie Projektu RStudio
Co tworzy Projekt RStudio?
Uruchamianie Projektu RStudio
Projekt RStudio kontra aktywny projekt usethis
Bieżący katalog roboczy i dyscyplina związana ze ścieżkami dostępu
Funkcja load_all()
Zalety funkcji load_all()
Inne sposoby wywołania load_all()
check() i R CMD check
Sposób pracy
Pod maską polecenia R CMD check
5. Zawartość pakietu
Alfa – działający skrypt
Bravo – lepsza wersja działającego skryptu
Charlie – oddzielny plik z funkcjami pomocniczymi
Delta – nieudana próba utworzenia pakietu
Echo – działający pakiet
Foxtrot – kompilacja kontra uruchomienie
Golf – efekty uboczne
Rozważania końcowe
Skrypt kontra pakiet
Wyszukiwanie w pakiecie
Pakiet kodu jest inny

Część II. Komponenty pakietu

6. Kod w języku R
Umieszczanie funkcji w plikach
Szybsze informacje zwrotne dzięki użyciu wywołania load_all()
Styl tworzenia kodu
Kiedy kod jest wykonywany?
Przykład: ścieżka dostępu zwrócona przez system.file()
Przykład: dostępne kolory
Przykład: alias dla funkcji
Szanowanie środowiska R
Zarządzanie stanem za pomocą pakietu withr
Przywracanie stanu za pomocą wywołania base::on.exit()
Odizolowanie efektów ubocznych
Gdy potrzebujesz efektów ubocznych
Nieustanne sprawdzanie poprawności
7. Dane
Dane wyeksportowane
Zachowanie pierwotnej historii danych pakietu
Dokumentowanie zbiorów danych
Znaki inne niż ASCII w danych
Dane wewnętrzne
Plik danych niezmodyfikowanych
Ścieżki dostępu plików
Funkcje pomocnicze pkg_example()
Stan wewnętrzny
Trwałe dane użytkownika
ROZDZIAŁ 8
8. Inne komponenty
Inne katalogi
Zainstalowane pliki
Plik CITATION w pakiecie
Narzędzia konfiguracji
CZĘŚĆ III

Część III. Metadane pakietu

9. Plik DESCRIPTION
Plik DESCRIPTION
Pola Title i Description – na czym polega działanie pakietu?
Pole Authors – kim jesteś?
Adres URL i zgłaszanie błędów
Pole License
Pola Imports, Suggests i Friends
Wersja minimalna
Pola Depends i LinkingTo
Problem z wersją R
Inne pola
Pola niestandardowe
10. Zależności – nastawienie i kontekst
Kiedy należy skorzystać z zależności?
Zależności nie są takie same
Postaw na podejście holistyczne, zrównoważone i ilościowe
Przemyślenia dotyczące zależności ściśle związanych z tidyverse
Imports czy Suggests?
Przestrzeń nazw
Uzasadnienie
Plik NAMESPACE
Ścieżka wyszukiwania
Wyszukiwanie funkcji dla kodu użytkownika
Wyszukiwanie funkcji w pakiecie
Dołączanie kontra wczytywanie
Imports czy Depends?
11. Zależności – praktyka
Niejasności związane z importowaniem
Konwencje zastosowane w tym rozdziale
Sposób pracy z plikiem NAMESPACE
Pakiet został wymieniony w polu Imports
Kod w katalogu R
W kodzie testu
W przykładach i w ulotkach
Pakiet jest wymieniony w polu Suggests
W kodzie zdefiniowanym w plikach katalogu R
W kodzie testowym
W przykładach i w ulotkach
Pakiet został wymieniony w polu Depends
W kodzie zdefiniowanym w plikach katalogu R oraz w kodzie testowym
W przykładach i w ulotkach
Pakiet jest zależnością niestandardową
Zależność od programistycznej wersji pakietu
Pole Config/Needs/*
Eksportowanie
Co należy wyeksportować?
Ponowne eksportowanie
Operacje importowania i eksportowania powiązane z systemem S3
12. Licencje
Szersza perspektywa
Kod, który tworzysz
Pliki kluczy
Więcej licencji dla kodu
Licencje dla danych
Ponowne licencjonowanie
Kod przekazany Tobie
Kod dołączony do pakietu
Zgodność licencji
Jak dołączyć kod?
Kod używany przez Ciebie

Część IV. Testowanie

13. Podstawy testowania
Dlaczego warto podjąć wysiłek związany z testowaniem?
Wprowadzenie do pakietu testthat
Struktura testów i praca z nimi
Konfiguracja początkowa
Tworzenie testu
Uruchamianie testów
Organizacja testu
Oczekiwania
Sprawdzanie równości
Sprawdzanie pod kątem błędów
Testy migawek
Skróty dla innych często spotykanych wzorców
14. Projektowanie zbioru testów
Co należy testować?
Pokrycie testami
Ogólne reguły dotyczące testowania
Testy samowystarczalne
Testy odizolowane
Planowanie niepowodzenia testu
Powtarzanie jest w porządku
Eliminowanie tarć między testowaniem interaktywnym i zautomatyzowanym
Pliki związane z testowaniem
Zniknąć z pola widzenia – pliki w katalogu R
tests/testthat.R
Pliki pomocnicze testthat
Pliki konfiguracyjne testthat
Pliki ignorowane przez testthat
Przechowywanie danych testowych
Gdzie będą zapisywane pliki podczas testów?
15. Zaawansowane techniki testowania
Przygotowywanie warunków początkowych testów
Tworzenie useful_thing za pomocą funkcji pomocniczej
Tworzenie (i usuwanie) lokalnego elementu useful_thing
Trwałe przechowywanie konkretnego elementu useful_thing
Budowanie własnych narzędzi testowania
Funkcja pomocnicza zdefiniowana w teście
Oczekiwania niestandardowe
Kiedy testowanie staje się trudne?
Pomijanie testu
Imitacje
Klucze tajne użytkownika
Uwagi specjalne dotyczące pakietów repozytorium CRAN
Pomijanie testu
Szybkość działania
Odtwarzalność
Testy niepewne
Higiena związana z procesem i systemem plików

Część V. Dokumentacja

16. Dokumentacja funkcji
Podstawy pracy z roxygen2
Sposób pracy z dokumentacją
Komentarze, bloki i tagi roxygen2
Najważniejsze funkcjonalności składni Markdown
Tytuł, opis, szczegóły
Tytuł
Opis
Szczegóły
Argumenty
Wiele argumentów
Dziedziczenie argumentów
Wartość zwrotna
Przykłady
Treść
Pozostawienie środowiska w jego początkowej postaci
Błędy
Zależności i wykonywanie warunkowe
Łączenie przykładów i tekstu
Wielokrotne wykorzystywanie dokumentacji
Wiele funkcji w jednym temacie
Dokumentacja dziedziczona
Dokumenty potomne
Temat pomocy dla pakietu
17. Ulotki
Sposób pracy podczas tworzenia ulotki
Metadane
Rada dotycząca tworzenia ulotek
Diagramy
Łącza
Ścieżki dostępu plików
Ile ulotek?
Publikacje naukowe
Uwagi szczególne dotyczące kodu ulotki
Artykuł zamiast ulotki
Jak są tworzone i sprawdzane ulotki?
Polecenie R CMD build i ulotki
Polecenie R CMD check i ulotki
18. Inne pliki Markdown
Plik README
Pliki README.Rmd i README.md
Plik NEWS
19. Witryna internetowa
Tworzenie witryny internetowej
Wdrożenie
Co dalej?
Logo
Indeks
Wygenerowane przykłady
Łącza
Ułożenie indeksu
Ulotki i artykuły
Łącza
Ułożenie indeksu
Artykuły niebędące ulotkami
Tryb programistyczny

Część VI. Obsługa techniczna i dystrybucja

20. Praktyki dotyczące tworzenia oprogramowania
Git i GitHub
Praktyka standardowa
Ciągła integracja
Akcje GitHuba
Wykonywanie polecenia R CMD check za pomocą akcji GitHuba
Inne zastosowania dla akcji GitHuba
21. Cykl życiowy
Ewolucja pakietu
Numer wersji pakietu
Konwencje numerów wersji pakietów tidyverse
Zachowanie wstecznej zgodności i przełomowe zmiany
Wersja główna, wersja mniejsza i wersja poprawki
Mechanizm wersji pakietu
Wady i zalety zmiany określanej jako przełomowa
Etapy cyklu życiowego i narzędzia wspomagające
Etapy cyklu życiowego i plakietki
Uznanie funkcji za przestarzałą
Uznanie argumentu za przestarzały
Komponent pomocniczy podczas uznawania za przestarzałe
Zmiana w zależności
Zastępowanie funkcji
22. Przekazanie pakietu do repozytorium CRAN
Określenie typu wydania
Początkowe wydanie poprzez repozytorium CRAN – kwestie specjalne
Polityki stosowane w repozytorium CRAN
Monitorowanie pod kątem zmian
Dokładne sprawdzenie wyniku wykonania polecenia R CMD check
Operacje sprawdzenia w repozytorium CRAN i powiązane z nimi usługi
Sprawdzanie zależności odwrotnych
Zależności odwrotne i przełomowe zmiany
Uaktualnienie komentarzy dla repozytorium CRAN
Proces przekazania pakietu do repozytorium CRAN
Tryby niepowodzenia
Świętowanie sukcesu