Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Introduction to RDoc


Published on

RDoc at <a href="">the May Rails Sydney meetup</a>

Published in: Technology, Education
  • Be the first to comment

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' 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