forked from steveklabnik/blog
/
contributing-to-ruby-s-documentation.html
176 lines (146 loc) · 7.87 KB
/
contributing-to-ruby-s-documentation.html
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
<!DOCTYPE html>
<html lang='en'>
<head>
<meta charset='utf8' />
<meta content='IE=edge,chrome=1' http-equiv='X-UA-Compatible' />
<title>Literate Programming - Contributing to Ruby's Documentation</title>
<link href='http://feeds.feedburner.com/steveklabnik' rel='alternate' type='application/rss+xml' />
<link href='/css/blueprint/screen.css' media='screen, projection' rel='stylesheet' />
<link href='/css/blueprint/print.css' media='print' rel='stylesheet' />
<!--[if lt IE 8]>
<link href='/css/blueprint/ie.css' media='screen, projection' rel='stylesheet' />
<![endif]-->
<link href='/css/site.css' rel='stylesheet' />
<script src='/js/modernizr-1.7.min.js'></script>
<script src='/js/jquery-1.6.min.js'></script>
<script src='/js/app.js'></script>
<script type='text/javascript'>
//<![CDATA[
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-4054156-1']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(ga);
})();
//]]>
</script>
</head>
<body>
<div class='container'>
<section class='span-14 prepend-2 append-2 clear' id='main'>
<h1>Contributing to Ruby's Documentation</h1>
<hr />
<p>Ruby 1.9.3 is coming out soon! <a href="http://blog.segment7.net/2011/05/09/ruby-1-9-3-documentation-challenge">drbrain has challenged the Ruby community to
improve its documentation</a>, but some people were asking about how to do so.
So I made a video!</p>
<p>Some small errata: drbrain has informed me that he should edit the Changelog,
not me. So don't do that. :)</p>
<iframe src="http://player.vimeo.com/video/23522731?title=0&byline=0&portrait=0" width="400" height="300" frameborder="0"></iframe>
<p><a href="http://vimeo.com/23522731">How to contribute to Ruby's documentation.</a> from <a href="http://vimeo.com/steveklabnik">Steve Klabnik</a> on <a href="http://vimeo.com">Vimeo</a>.</p>
<p>If you don't want to watch me talk about it, here's the same info, in text:</p>
<p>Getting the Ruby source is pretty easy. You can find it on GitHub, here:
<a href="http://github.com/ruby/ruby">http://github.com/ruby/ruby</a> . Click the "fork" button and clone down your
own fork:</p>
<pre><code>$ git clone git@github.com:YOURUSERNAME/ruby.git
</code></pre>
<p>After that's done, type <code>cd ruby</code> and add the main project as an upstream. This will
let you keep up-to-date with the latest changes:</p>
<pre><code>$ git remote add upstream https://github.com/ruby/ruby.git
$ git fetch upstream
</code></pre>
<p>Okay! Now that you're all set up, poke around and find something that needs
documented. I like to just look through the source, but you can also look
<a href="http://segment7.net/projects/ruby/documentation_coverage.txt">here</a> for a list of things that have no docs. Documentation is written in
rdoc, and I'd check the recent commits that drbrain has been making to guide
you in style. <a href="https://github.com/ruby/ruby/commit/071a678a156dde974d8e470b659c89cb02b07b3b">This commit</a>, for example, is a pretty good template. You
can also check out the formatting guides <a href="http://rdoc.rubyforge.org/RDoc/Markup.html">here</a>. There's also <a href="http://rdoc.rubyforge.org/RDoc/Parser/Ruby.html">this</a>
which explains some directives for .rb files and <a href="http://rdoc.rubyforge.org/RDoc/Parser/C.html">this</a> which handles
directives for .c files.</p>
<p>Now that you've made a change to the documentation, you can regenerate the
docs by using rdoc. First, grab the latest version from rubygems:</p>
<p> $ gem install rdoc</p>
<p>Always best to have the latest tools. Now do this to generate the docs:</p>
<pre><code>$ rdoc --o tmpdoc lib/rss*
</code></pre>
<p>I'm passing it in an output directory with op, since the doc directory is not
an rdoc directory. rdoc will complain and refuse to overwrite those files,
which is a good thing. I'm also passing in a pattern of what to compile
documentation for, compiling all of it takes a few minutes! In this case, I
chose to document the rss library.</p>
<p>Now you have a website in rdocout. Open up its index.html, and poke around for
what you've changed. If it all looks good, you're ready to make a patch!</p>
<pre><code>$ rm -r rdocout
$ git add .
$ git commit -m "adding documentation for $SOMETHING"
</code></pre>
<p>Now, you have two options here. One is to simply push the change up to GitHub,
and make a pull request.</p>
<pre><code>$ git push origin
</code></pre>
<p>... aaand pull request. The core Ruby development doesn't really happen on
GitHub though, and so your patch may take a while to get included. If you
really want to do it right, submit a patch to RedMine. We'll use git to make
this patch:</p>
<pre><code>$ git format-patch HEAD~1
</code></pre>
<p>This says "make a patch out of the last commit." It'll tell you a file name,
it should start with 000.</p>
<p>Now, sign up for the Ruby RedMine <a href="http://redmine.ruby-lang.org/account/register">here</a>. Once you've clicked the
confirmation email, <a href="http://redmine.ruby-lang.org/projects/ruby-19/issues/new">open a new ticket</a>, and assign it to Eric Hodel,
category DOC, and give it your Ruby version, even though it's not a big deal
here. Click 'choose file' and pick your patch, then 'create and continue' and
BAM! You're done!</p>
<p>Let's all pitch in and make this the best documented Ruby release ever! In
writing documentation, you might even find some things that you'd like to help
improve. ;)</p>
<h3>Have Something to say?</h3>
<hr />
<p>
<p>I'd love to hear from you. I don't accept comments directly, but please
<a href="mailto:steve@steveklabnik.com">email me</a> with any feedback,
positive or negative. I always revise posts with the interesting parts
of these discussions. Thanks!</p>
</p>
</section>
<section class='span-5 prepend-1 last' id='right'>
<img src='http://en.gravatar.com/userimage/5335489/ee56a7574df33ed8748160494c930b98.jpg?size=190' />
<aside>
<h4>Hi there, I'm Steve.</h4>
<p>
I write both code and prose. Here's some of my thoughts about software,
literature, art and code, with some politics thrown in on occasion.
You might also enjoy <a href="http://steveklabnik.com/">my website</a>.
</p>
</aside>
<nav>
<h4>See them all</h4>
<p>
You're viewing a single post, but if you'd like to see
the list of everything I've written, just <a href="/">go here</a>.
</p>
<h4>Popular Posts</h4>
<p>Here are some of my most-viewed articles.</p>
<ul>
<li>
<a href='/2010/03/03/why-bother-creating.html'>Why bother creating?</a>
</li>
<li>
<a href='/2010/08/19/a-word-about-why-whyday-and-hackety-hack.html'>A word about _why, #whyday, and Hackety Hack</a>
</li>
<li>
<a href='/2010/11/17/the-hardest-decision-i-ve-ever-made.html'>The hardest decision I've ever made</a>
</li>
<li>
<a href='/2010/03/08/create-a-more-compelling-experience-for-your-users-through-game-mechanics.html'>Create a more compelling experience for your users through game mechanics</a>
</li>
<li>
<a href='/2010/07/17/what-to-know-before-debating-type-systems.html'>What to know before debating type systems</a>
</li>
</ul>
</nav>
</section>
</div>
</body>
</html>