Introduction to RDoc
1 like923 views
RDoc at <a href="http://rubyonrails.com.au/past/2007/4/16/sydney_may_2007_meetup/">the May Rails Sydney meetup</a>
![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](https://image.slidesharecdn.com/introduction-to-rdoc-1849/85/Introduction-to-RDoc-15-320.jpg)
Introduction to RDoc
- 2. RDoc
- 3. GEMS of OCEANIA what basics do we need for a newcomer to publish their first gem?
- 4. the Perils of Documentation
- 5. skills technical skills (see: this preso), writing skills (sorry, cant help)
- 6. time writing documentation and keeping it up-to-date takes time
- 7. change code and architecture changes, domain changes e.g. wikis and .docs get dusty & crufty
- 8. RDoc let us see how RDoc addresses these perils
- 9. skills theyre just Ruby comments, with a few formatting tags it autolinks, autogenerates, etc. Your mum could RDoc (maybe, ok prolly not)
- 10. for those writing skills...
- 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. change its in your code, therefore the chance of it staying up-to-date is high
- 13. Demo I running RDoc on a simple file: rdoc somefile.rb
- 14. RDocTask
- 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. Demo II creating a Rakefile with an RDocTask, then seeing what Rake tasks it creates, and finally running rake: rake -T; rake doc
- 17. Rails
- 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. Demo III generating docs for your Rails app: rake doc:app; rake doc:api
- 20. Sexiness
- 21. Demo IV using Evan Weavers Allison RDoc template My suggestion: use that and customise the CSS.
- 22. interlude
- 23. Formatting
- 24. = Level One Heading == Level Two Heading etc. headings!
- 25. # Heres a list: # # * Item 1 # * Item 2 lists!
- 26. # Add another: # # 1. Item 1 # 2. Item 2 lists again!
- 27. :nodoc: Prevent RDoc from documenting a class, method or module.
- 28. :nodoc:all Prevent RDoc from documenting a class or module and all of the bits within it.
- 29. :doc: Force RDoc to include a class, module or method in the documentation.
- 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.
- 32. Thanks! Tim Lucas toolmantim.com