DZone Snippets: documentation code

POD - Plain Old Documentation

db-keen (db) — Thu, 26 Jun 2008 04:45:55 GMT



#!/usr/bin/env tt

# Author::    Daniel Brumbaugh Keeney (http://rubyforge.org/users/db-keen)

# Copyright:: 2008 Daniel Brumbaugh Keeney

# License::   GPLv3+

#

# This program is free software: you can redistribute it and/or modify

# it under the terms of the GNU General Public License as published by

# the Free Software Foundation, either version 3 of the License, or

# (at your option) any later version.

#

# This program is distributed in the hope that it will be useful,

# but WITHOUT ANY WARRANTY; without even the implied warranty of

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

# GNU General Public License for more details.

#

# You should have received a copy of the GNU General Public License

# along with this program.  If not, see .



grammar Pod



  rule podfile

    ignored_stuff

    paragraph+

  end



  rule pod_content

    directive+

  end



  rule command_paragraph

    '=' (

      head_directive /

      item_directive /

      alternate_content_directive /

      cut_directive /

      over_directive /

      pod_directive

    ) "\n"

  end



  rule pod_directive

    'pod' ( space ( !newline_sequence . )* )? newline_sequence blank_line+

    

  end



  rule over_directive

    content:(paragraph+) '=back'

    

  end





  rule cut_directive

    'cut' ignored_stuff

    

  end



  rule ignored_stuff

    ( !command_paragraph ( !newline_sequence . )* newline_sequence? )*

    

  end



  rule item_directive

    'item' space+ liststyle:( !space . )+ space+ content:( !newline_sequence . )+

  end



  rule head_directive

    'head' [1234] space content:( !newline_sequence . )+

  end



  rule alternate_content_directive

    'begin' space+ format:( !newline_sequence . )+ newline_sequence

    content:( !"=end" . )+

    '=end' space+ format_again:( !newline_sequence . )+

  end



  rule inline_formatting

    uppercase_letter '<'

    (

      content:( !'>' . )+ /

      thickly_wrapped_inline_formatting

    ) '>'

  end



  # This rule is not in compliance with spec. The actual pod

  # specification cannot be implemented in Treetop. Luckily, I wrote

  # a rule in ruby to replace this one.

  rule thickly_wrapped_inline_formatting

    '<' (

      space content:( !( space+ ">>" ) . )+ space+ /

      thickly_wrapped_inline_formatting

    ) '>'

  end



  rule paragraph

    verbatim_paragraph /

    command_paragraph /

    ordinary_paragraph

  end



  rule ordinary_paragraph

    !space

    !( '=' [a-zA-Z] )

    non_blank_line+

    blank_line+

    

  end



  rule verbatim_paragraph

    [ \t]

    non_blank_line+

    blank_line+

    

  end



  rule data_paragraph

    non_blank_line+

    blank_line+

    

  end



  rule uppercase_letter

    [ABCDEFGHIJKLMNOPQRSTUVWXYZ]

  end



  rule space

    [\t ]

  end



  rule newline_sequence

    "\r\n" / [\n\r]

  end



  rule blank_line

    space* ( !. / newline_sequence )

  end



  rule non_blank_line

    space* ( !newline_sequence . )+ ( !. / newline_sequence )

  end



end

Creating a simple Ruby Class documenter

jrobertson (James Robertson) — Tue, 19 Feb 2008 22:33:54 GMT

This Ruby code stores the class name, method names, and method parameters from a ruby file in an XML file. I have a habit of forgetting what methods I use in my classes, with this code I should at least be able to build up a quick class browser.



#!/usr/bin/ruby



# file: ruby2xml.rb



require 'rexml/document'

include REXML



class Ruby2XML



  attr :doc

  

  def initialize(buffer)



    @outline = buffer.scan(/^class\s+(\w+)(\s+)?|def\s+(\w+)(\s+)?\(?(.*(?=\)))?/)

    @doc = Document.new

    @doc.add_element('ruby')

    o_class = Element.new('class')

    o_class.add_attribute('name', get_class_name)

    o_methods = Element.new('methods')

    

    #get the methods

    1.upto(get_method_count) {|i| o_methods.add_element(add_method(@outline[i])) }

    o_class.add_element(o_methods)

    @doc.root.add_element o_class



  end

  

  private # everything below this point is private

  

  def get_class_name()

    @outline[0][0]

  end

  

  def get_method_count

    mc = -1

    @outline.each {|m| mc += 1}

    mc 

  end

  

  def add_method(amethod)

    o_method = Element.new('method')

    o_method.add_attribute('name',amethod[2]) #get the method name

    o_params = Element.new('params')



    if amethod[4] then # get the parameter names

      amethod[4].split(',').each {|a| o_params.add_element(add_param(a.strip))}

    end

    

    o_method.add_element(o_params)    

    o_method

  end

  

  def add_param(param)

    o_param = Element.new('param')

    o_param.text = param

    o_param

  end

      

end



if __FILE__ == $0



  buffer = File.new('ruby2xml.rb').read

  rx2 = Ruby2XML.new(buffer)

  

  file = File.new('ruby2xml.xml','w')

  file.puts rx2.doc

  file.close



end

Note: This is just my first attempt at building some kind of Ruby code documenter, but it should be good enough for my needs at the moment.

output





  

    

      buffer

      

      

      amethod

      param

Browse pydoc locally ...

kumar303 (kumar mcmillan) — Fri, 08 Apr 2005 03:39:18 GMT

Opens pydoc in your browser. If pydoc has not been started it starts it for you.



#!/bin/bash



PYDOC=`which pydoc`

if [ ! -x ${PYDOC} ]

then

    echo "could not find executable pydoc (tried: ${PYDOC})"

    exit 1

fi



# passthru ...

if [ $# -gt 0 ]

then

    ${PYDOC} $@

    exit $?

fi



#--------------------------------------

# or else... start it up automagically :



PYDOC_PORT=9000

PYDOC_SERVER=http://localhost:${PYDOC_PORT}/

running=0

pydoc_pses=0



function browse_docs()

{

    open ${PYDOC_SERVER}

}



for ps in `ps ax | grep "${PYDOC}" | awk '{ print $1 }'`

do

    let pydoc_pses++

done



if [ $pydoc_pses -ge 2 ]

then

    browse_docs

else

    ${PYDOC} -p ${PYDOC_PORT} &

    until `curl -o /dev/null ${PYDOC_SERVER} &>/dev/null`

    do

        echo "waiting for pydoc server ..."

        sleep 2

    done

    browse_docs

fi

exit 0