Introduction to RDoc

1,859 views
1,761 views

Published on

RDoc at <a href="http://rubyonrails.com.au/past/2007/4/16/sydney_may_2007_meetup/">the May Rails Sydney meetup</a>

Published in: Technology, Education
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
1,859
On SlideShare
0
From Embeds
0
Number of Embeds
33
Actions
Shares
0
Downloads
35
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

Introduction to RDoc

  1. 1. pre-show interlude
  2. 2. RDoc
  3. 3. GEMS of OCEANIA what basics do we need for a newcomer to publish their first gem?
  4. 4. the Perils of Documentation
  5. 5. skills technical skills (see: this preso), writing skills (sorry, cant help)
  6. 6. time writing documentation and keeping it up-to-date takes time
  7. 7. change code and architecture changes, domain changes e.g. wikis and .docs get dusty & crufty
  8. 8. RDoc let us see how RDoc addresses these perils
  9. 9. skills theyre just Ruby comments, with a few formatting tags it autolinks, autogenerates, etc. Your mum could RDoc (maybe, ok prolly not)
  10. 10. for those writing skills...
  11. 11. time theyre just comments. You dont need to document the self-explanatory, but chances are youre already commenting tricky bits of code. Why not use that to create reference docs?
  12. 12. change its in your code, therefore the chance of it staying up-to-date is high
  13. 13. Demo I running RDoc on a simple file: rdoc somefile.rb
  14. 14. RDocTask
  15. 15. 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 = quot;READMEquot; # page to start on rdoc.title = quot;My App's Documentationquot; rdoc.rdoc_dir = 'doc' # rdoc output folder rdoc.options << '--line-numbers' << '--inline-source' end
  16. 16. Demo II creating a Rakefile with an RDocTask, then seeing what Rake tasks it creates, and finally running rake: rake -T; rake doc
  17. 17. Rails
  18. 18. $ rake -T doc rake doc:app # Build the app HTML Files rake doc:clobber_app # Remove rdoc products rake doc:clobber_plugins # Remove plugin documentation rake doc:clobber_rails # Remove rdoc products rake doc:plugins # Generate documation for all installed plugins rake doc:rails # Build the rails HTML Files rake doc:reapp # Force a rebuild of the RDOC files rake doc:rerails # Force a rebuild of the RDOC files
  19. 19. Demo III generating docs for your Rails app: rake doc:app; rake doc:api
  20. 20. Sexiness
  21. 21. Demo IV using Evan Weavers Allison RDoc template My suggestion: use that and customise the CSS.
  22. 22. interlude
  23. 23. Formatting
  24. 24. = Level One Heading == Level Two Heading etc. headings!
  25. 25. # Here’s a list: # # * Item 1 # * Item 2 lists!
  26. 26. # Add another: # # 1. Item 1 # 2. Item 2 lists again!
  27. 27. :nodoc: Prevent RDoc from documenting a class, method or module.
  28. 28. :nodoc:all Prevent RDoc from documenting a class or module and all of the bits within it.
  29. 29. :doc: Force RDoc to include a class, module or method in the documentation.
  30. 30. 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.
  31. 31. post-show interlude
  32. 32. Thanks! Tim Lucas toolmantim.com

×