Dokumentacja Ruby i Rails

W trakcie nauki i korzystania z języka, jedną z niezbędnych rzeczy jest dobra i wygodna dokumentacja. Gdzie można taką znaleźć dla Rubiego i Railsów? Dziś odpowiem na to pytanie. Poniższe porady przydadzą się głównie początkującym adeptom Rubiego, jeśli więc uważasz, że wiesz jak korzystać z dokumentacji, upewnij się tylko, że znasz stronę railsapi.com.

Podstawowa dokumentacja

Pierwsze miejsce, gdzie można się udać to: http://www.ruby-doc.org/core/. Znajdziemy tam najbardziej kanoniczne źródło, wygenerowane z kodu przy pomocy Rdoc opisujące core języka, a opis biblioteki standardowej mieszka zaś tutaj: http://www.ruby-doc.org/stdlib/. Dokumentacja do innych wersji języka (1.8.7 oraz 1.9) dostępna jest pod adresem: http://ruby-doc.org/ Najprostsza dokumentacja Railsów to: http://api.rubyonrails.org/ .

Apidock – przeglądanie wersji

Dużo przyjemniej od wyżej wymienionych, używa się serwisu: APIdock. Oprócz Rubiego oraz Railsów, znajdziemy tam też dokumentację Rspec’a.

Według mnie główną zaletą tego serwisu, jest banalnie prosta możliwość zobaczenia jak dowolna metoda i klasa wygląda w różnych wydaniach. Weźmy na warsztat dokumentację dla funkcji render.

Widzimy, że zmiany w tej funkcji zachodziły w wersjach 1.1.0, 1.2.0, 2.0.0, 2.2.1 oraz 2.3.1. Teraz wystarczy tylko kliknięcie, by się przekonać, że np w wersji 2.2.1 pojawiła się możliwość przekazania do partiala parametru object.

#Renders the partial, making @new_person available through
# the local variable 'person'
render :partial => "person", :object => @new_person

APIdock okazuje się nieocenione, kiedy musimy zmierzyć się z kodem wykorzystującym archaiczną (czyli zazwyczaj starszą niż rok) wersję railsów. Pomaga również sprawdzić dlaczego znajoma funkcja zachowuje się inaczej niż do tego byliśmy przyzwyczajeni.

Railsapi – szukasz, masz

Wadą obu poprzednich stron jest fatalna wyszukiwarka, a w przypadku Rdoc, właściwie jej brak. Problem ten rozwiązuje http://railsapi.com/, z którego to korzystam na co dzień. Oprócz bardzo dobrze działającej wyszukiwarki, można w nim przygotować dokumentację, zawierającą informację o kilku najpopularniejszych gemach, oczywiście z wyborem wersji. Tak przygotowaną paczkę można albo pobrać, albo przeglądać online.

Dokumentacja gemów

Aby zobaczyć dokumentację gemów, które zainstalowaliśmy, wcale nie trzeba szukać daleko. Wystarczy wywołać polecenie:

gem server

Uruchamia ono pod adresem http://0.0.0.0:8808, przyjemną stronę, na której możemy znaleźć zarówno linki do dokumentacji każdego gemu, jak i dokumentację w formacie Rdoc, o ile ją zainstalowaliśmy. To ostatnie jest sczególnie przydatne, gdy nie posiadamy połączenia z Internetem.

W ostateczności możemy zawsze skorzystać z dokumentacji ri, bezpośrednio z linii poleceń. Na przykład aby dobrać się do dokumentacji klasy Array, należy wpisać:

ri Array

Szybsza instalacja gemów

Na koniec mała rada, dla osób, które nie korzystają i nie mają zamiaru korzystać ani z Rdoc’a, ani z ri. Na pewno przydadzą im się opcje --no-ri oraz --no-rdoc. Na przykład instalacja Rspec’a z wykorzystaniem poniższego polecenia, jest dużo szybsza, gdyż jest pomijana dokumentacja, której generowanie zajmuje zazwyczaj najwięcej czasu.

gem install rspec --no-ri --no-rdoc

Można również na stałe wyłączyć generowanie dokumentacji, dodając w pliku $HOME/.gemrc następującą linijkę:

gem: --no-ri --no-rdoc


Komentarze

  1. Seban 18.03.2010

    Comment Arrow

    Ja korzystam z apidocka i jestem zadowolony z ich wyszukiwarki. 🙂 Na plus można podać, że w apidock są komentarze ludzi, które często zawierają jakiś konkretny przykład użycia metody.


  2. Gąbek 18.03.2010

    Comment Arrow

    Ja polecam jeszcze: http://www.gotapi.com Nie tylko ror. Wszystko w jednym miejscu pod ręką


  3. tjeden 18.03.2010

    Comment Arrow

    Fakt, komentarze na apidock, są całkiem przydatne, ale wyszukiwarka jest tam toporna.

    Gotapi bardzo ładne. Nie znałem.

    Dziś dowiedziałem się tez o webowej wersji ri:
    http://proutils.github.com/webri/




O autorze

Aleksander Dąbrowski

Od 2008 zawodowo programuje w Ruby i Railsach. Jest maniakiem prostych i eleganckich rozwiązań, nie boi się usuwania brzydkiego kodu. Uwielbia dzielić się wiedzą, a w wolnych chwilach naprawia samochody.