Introduction to RDoc
-
Upload
tim-lucas -
Category
Technology
-
view
124 -
download
0
description
Transcript of Introduction to RDoc
![Page 1: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/1.jpg)
pre-show interlude
![Page 2: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/2.jpg)
RDoc
![Page 3: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/3.jpg)
GEMS of OCEANIA
what basics do we need for a newcomerto publish their first gem?
![Page 4: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/4.jpg)
the Perils of Documentation
![Page 5: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/5.jpg)
skills
technical skills (see: this preso),writing skills (sorry, cant help)
![Page 6: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/6.jpg)
time
writing documentation andkeeping it up-to-date takes time
![Page 7: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/7.jpg)
change
code and architecture changes, domain changese.g. wikis and .docs get dusty & crufty
![Page 8: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/8.jpg)
RDoc
let us see how RDoc addresses these perils
![Page 9: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/9.jpg)
skills
theyre just Ruby comments, with a few formatting tags it autolinks, autogenerates, etc.
Your mum could RDoc (maybe, ok prolly not)
![Page 10: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/10.jpg)
for those writing skills...
![Page 11: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/11.jpg)
time
theyre just comments. You dont need to document theself-explanatory, but chances are youre already
commenting tricky bits of code.Why not use that to create reference docs?
![Page 12: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/12.jpg)
change
its in your code, therefore the chance of itstaying up-to-date is high
![Page 13: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/13.jpg)
Demo I
running RDoc on a simple file:rdoc somefile.rb
![Page 14: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/14.jpg)
RDocTask
![Page 15: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/15.jpg)
require 'rake/rdoctask'
Rake::RDocTask.new do |rdoc| files = ['README', 'LICENSE', 'COPYING', 'lib/**/*.rb', 'doc/**/*.rdoc', 'test/*.rb'] rdoc.rdoc_files.add(files) rdoc.main = "README" # page to start on rdoc.title = "My App's Documentation" rdoc.rdoc_dir = 'doc' # rdoc output folder rdoc.options << '--line-numbers' << '--inline-source'end
![Page 16: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/16.jpg)
Demo II
creating a Rakefile with an RDocTask, then seeing what Rake tasks it creates, and finally
running rake: rake -T; rake doc
![Page 17: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/17.jpg)
Rails
![Page 18: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/18.jpg)
$ rake -T docrake doc:app # Build the app HTML Filesrake doc:clobber_app # Remove rdoc productsrake doc:clobber_plugins # Remove plugin documentationrake doc:clobber_rails # Remove rdoc productsrake doc:plugins # Generate documation for all installed pluginsrake doc:rails # Build the rails HTML Filesrake doc:reapp # Force a rebuild of the RDOC filesrake doc:rerails # Force a rebuild of the RDOC files
![Page 19: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/19.jpg)
Demo III
generating docs for your Rails app:rake doc:app; rake doc:api
![Page 20: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/20.jpg)
Sexiness
![Page 21: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/21.jpg)
Demo IV
using Evan Weavers Allison RDoc templateMy suggestion: use that and customise the CSS.
![Page 22: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/22.jpg)
interlude
![Page 23: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/23.jpg)
Formatting
![Page 24: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/24.jpg)
= Level One Heading == Level Two Headingetc.
headings!
![Page 25: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/25.jpg)
# Here’s a list:## * Item 1# * Item 2
lists!
![Page 26: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/26.jpg)
# Add another:## 1. Item 1# 2. Item 2
lists again!
![Page 27: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/27.jpg)
:nodoc:
Prevent RDoc from documenting a class, method or module.
![Page 28: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/28.jpg)
:nodoc:all
Prevent RDoc from documenting a class or module and all of the bits within it.
![Page 29: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/29.jpg)
:doc:
Force RDoc to include a class, module or method in the documentation.
![Page 30: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/30.jpg)
def fred # :yields: index, position ... yield line, address
RDoc automatically tries to figure out what your method yields from the variable names. Using :yields: you can override this.
![Page 31: Introduction to RDoc](https://reader033.fdocuments.net/reader033/viewer/2022051014/54c8915e4a7959e51e8b458c/html5/thumbnails/31.jpg)
post-show interlude