1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285
|
= README.DEV
Copyright:: Copyright (C) 2005, 2006 Toshiaki Katayama <k@bioruby.org>
Copyright:: Copyright (C) 2006, 2008 Jan Aerts <jandot@bioruby.org>
= HOW TO CONTRIBUTE TO THE BIORUBY PROJECT?
There are many possible ways to contribute to the BioRuby project,
such as:
* Join the discussion on the BioRuby mailing list
* Send a bug report or write a bug fix patch
* Add and correct documentation
* Develop code for new features, etc.
All of these are welcome! However, this document describes the last option,
how to contribute your code to the BioRuby distribution.
We would like to include your contribution as long as the scope of
your module meets the field of bioinformatics.
== Git
Bioruby is now under git source control at http://github.com/bioruby/bioruby.
There are two basic ways to contribute: with patches or pull requests. Both are
explained on the bioruby wiki at http://bioruby.open-bio.org/wiki.
= LICENSE
If you would like your module to be included in the BioRuby distribution,
you need to give us right to change the license of your module to make it
compatible with other modules in BioRuby.
BioRuby was previously distributed under the LGPL license, but now is
distributed under the same terms as Ruby.
= CODING STYLE
You will need to follow the typical coding styles of the BioRuby modules:
== Use the following naming conventions
* CamelCase for module and class names
* '_'-separated_lowercase for method names
* '_'-separated_lowercase for variable names
* all UPPERCASE for constants
== Indentation must not include tabs
* Use 2 spaces for indentation.
* Don't replace spaces to tabs.
== Comments
Don't use <tt>=begin</tt> and <tt>=end</tt> blocks for comments. If you need to
add comments, include it in the RDoc documentation.
== Documentation should be written in the RDoc format in the source code
The RDoc format is becoming the popular standard for Ruby documentation.
We are now in transition from the previously used RD format to the RDoc
format in API documentation.
Additional tutorial documentation and working examples are encouraged
with your contribution. You may use the header part of the file for
this purpose as demonstrated in the previous section.
== Standard documentation
=== of files
Each file should start with a header, which covers the following topics:
* copyright
* license
* description of the file (_not_ the classes; see below)
* any references, if appropriate
The header should be formatted as follows:
#
# = bio/db/hoge.rb - Hoge database parser classes
#
# Copyright:: Copyright (C) 2001, 2003-2005 Bio R. Hacker <brh@example.org>,
# Copyright:: Copyright (C) 2006 Chem R. Hacker <crh@example.org>
#
# License:: The Ruby License
#
# == Description
#
# This file contains classes that implement an interface to the Hoge database.
#
# == References
#
# * Hoge F. et al., The Hoge database, Nucleic. Acid. Res. 123:100--123 (2030)
# * http://hoge.db/
#
require 'foo'
module Bio
autoload :Bar, 'bio/bar'
class Hoge
:
end # Hoge
end # Bio
=== of classes and methods within those files
Classes and methods should be documented in a standardized format, as in the
following example (from lib/bio/sequence.rb):
# == Description
#
# Bio::Sequence objects represent annotated sequences in bioruby.
# A Bio::Sequence object is a wrapper around the actual sequence,
# represented as either a Bio::Sequence::NA or a Bio::Sequence::AA object.
# For most users, this encapsulation will be completely transparent.
# Bio::Sequence responds to all methods defined for Bio::Sequence::NA/AA
# objects using the same arguments and returning the same values (even though
# these methods are not documented specifically for Bio::Sequence).
#
# == Usage
#
# require 'bio'
#
# # Create a nucleic or amino acid sequence
# dna = Bio::Sequence.auto('atgcatgcATGCATGCAAAA')
# rna = Bio::Sequence.auto('augcaugcaugcaugcaaaa')
# aa = Bio::Sequence.auto('ACDEFGHIKLMNPQRSTVWYU')
#
# # Print in FASTA format
# puts dna.output(:fasta)
#
# # Print all codons
# dna.window_search(3,3) do |codon|
# puts codon
# end
#
class Sequence
# Create a new Bio::Sequence object
#
# s = Bio::Sequence.new('atgc')
# puts s # => 'atgc'
#
# Note that this method does not intialize the contained sequence
# as any kind of bioruby object, only as a simple string
#
# puts s.seq.class # => String
#
# See Bio::Sequence#na, Bio::Sequence#aa, and Bio::Sequence#auto
# for methods to transform the basic String of a just created
# Bio::Sequence object to a proper bioruby object
# ---
# *Arguments*:
# * (required) _str_: String or Bio::Sequence::NA/AA object
# *Returns*:: Bio::Sequence object
def initialize(str)
@seq = str
end
# The sequence identifier. For example, for a sequence
# of Genbank origin, this is the accession number.
attr_accessor :entry_id
# An Array of Bio::Feature objects
attr_accessor :features
end # Sequence
Preceding the class definition (<tt>class Sequence</tt>), there is at least a
description and a usage example. Please use the +Description+ and +Usage+
headings. If appropriate, refer to other classes that interact with or are
related to the class.
The code in the usage example should, if possible, be in a format that a user
can copy-and-paste into a new script to run. It should illustrate the most
important uses of the class. If possible and if it would not clutter up the
example too much, try to provide any input data directly into the usage example,
instead of refering to ARGV or ARGF for input.
dna = Bio::Sequence.auto('atgcatgcATGCATGCAAAA')
Otherwise, describe the input shortly, for example:
# input should be string consisting of nucleotides
dna = Bio::Sequence.auto(ARGF.read)
Methods should be preceded by a comment that describes what the method does,
including any relevant usage examples. (In contrast to the documentation for
the class itself, headings are not required.) In addition, any arguments should
be listed, as well as the type of thing that is returned by the method. The
format of this information is as follows:
# ---
# *Arguments*:
# * (required) _str_: String or Bio::Sequence::NA
# * (optional) _nr_: a number that means something
# *Returns*:: true or false
Attribute accessors can be preceded by a short description.
== Exception handling
Don't use
$stderr.puts "WARNING"
in your code. Instead, try to avoid printing error messages. For fatal errors,
use +raise+ with an appropriate message.
== Testing code should use 'test/unit'
Unit tests should come with your modules by which you can assure what
you meant to do with each method. The test code is useful to make
maintenance easy and ensure stability. The use of
if __FILE__ == $0
is deprecated.
== Using autoload
To quicken the initial load time we have replaced most of 'require' to
'autoload' since BioRuby version 0.7. During this change, we have found
some tips:
You should not separate the same namespace into several files.
* For example, if you have separated definitions of the Bio::Foo
class into two files (e.g. 'bio/foo.rb' and 'bio/bar.rb'), you
need to resolve the dependencies (including the load order)
yourself.
* If you have a defined Bio::Foo in 'bio/foo.rb' and a defined
Bio::Foo::Bar in 'bio/foo/bar.rb' add the following line in the
'bio/foo.rb' file:
autoload :Bar, 'bio/foo/bar'
You should not put several top level namespaces in one file.
* For example, if you have Bio::A, Bio::B and Bio::C in the file
'bio/foo.rb', you need
autoload :A, 'bio/foo'
autoload :B, 'bio/foo'
autoload :C, 'bio/foo'
to load the module automatically (instead of require 'bio/foo').
In this case, you should put them under the new namespace like
Bio::Foo::A, Bio::Foo::B and Bio::Foo::C in the file 'bio/foo',
then use
autoload :Foo, 'bio/foo'
so autoload can be written in 1 line.
= NAMESPACE
Your module should be located under the top-level module Bio and put under
the 'bioruby/lib/bio' directory. The class/module names and the
file names should be short and descriptive.
There are already several sub directories in 'bioruby/lib':
bio/*.rb -- general and widely used basic classes
bio/appl/ -- wrapper and parser for the external applications
bio/data/ -- basic biological data
bio/db/ -- flatfile database entry parsers
bio/io/ -- I/O interfaces for files, RDB, web services etc.
bio/util/ -- utilities and algorithms for bioinformatics
If your module doesn't match any of the above, please propose
an appropriate directory name when you contribute. Please let the staff
discuss on namespaces (class names), API (method names) before commiting
a new module or making changes on existing modules.
= MAINTENANCE
Finally, please maintain the code you've contributed. Please let us know (on
the bioruby list) before you commit, so that users can discuss on the change.
|