You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* add link to talk and slides
* add anchors to step-by-step-guide
* footer link to about
* 80 width columns
* note about .patch extension on github
* note about passing files to rdoc -C1
* update contact info and community resources
<ahref="http://www.youtube.com/watch?v=4oBl1PmO4K0">Presentation</a> with <ahref="https://speakerdeck.com/zzak/contributing-to-ruby">slides</a> on Contributing to Ruby</a>
40
49
</li>
41
50
<li><ahref="http://blog.steveklabnik.com/2011/05/10/contributing-to-ruby-s-documentation.html">Article & screencast on the documentation process</a></li>
Copy file name to clipboardExpand all lines: _posts/2011-10-06-step-by-step-guide.markdown
+56-11Lines changed: 56 additions & 11 deletions
Original file line number
Diff line number
Diff line change
@@ -5,6 +5,7 @@ tags:
5
5
- help
6
6
---
7
7
8
+
<aname="SetUp"></a>
8
9
## Getting Set Up
9
10
10
11
Fork documenting-ruby's fork of Ruby [on github](https://github.com/documenting-ruby/ruby).
@@ -21,24 +22,44 @@ git fetch upstream
21
22
git merge upstream/trunk
22
23
{% endhighlight %}
23
24
24
-
Choose some code to document. You can use our [suggestions for code to document](undocumented-areas.html) or follow these instructions to generate your own list of undocumented code. Check documenting-ruby's [fork of Ruby issues](https://github.com/documenting-ruby/ruby/issues) for a list of documentation other people are working on.
25
+
Choose some code to document. You can use our [suggestions for code to
26
+
document](undocumented-areas.html) or follow these instructions to generate
27
+
your own list of undocumented code. Check documenting-ruby's [fork of Ruby
28
+
issues](https://github.com/documenting-ruby/ruby/issues) for a list of
29
+
documentation other people are working on.
25
30
26
31
Get a list of undocumented code (you must have rdoc >= 3.3 for this to work):
27
32
{% highlight bash %}
28
33
rdoc -C1 > documentation_coverage.txt
29
34
{% endhighlight %}
30
35
31
-
Search for "is not documented" in "documentation_coverage.txt". Find something that interests you, and document it. You can see how much of Ruby is documented by looking at the stats at the bottom of the file.
36
+
You can also pass a list of files to check the documentation coverage, if you
37
+
already have something in mind:
38
+
{% highlight bash %}
39
+
rdoc -C1 lib/drb* > documentation_coverage.txt
40
+
{% endhighlight %}
41
+
42
+
Search for "is not documented" in "documentation_coverage.txt". Find something
43
+
that interests you, and document it. You can see how much of Ruby is documented
44
+
by looking at the stats at the bottom of the file.
32
45
46
+
<aname="Documenting"></a>
47
+
<aclass="top"href="#">top</a>
33
48
## Documenting
34
49
35
-
To help others know what you're documenting, [open an issue](https://github.com/documenting-ruby/ruby/issues/new) on documenting-ruby's fork of Ruby.
50
+
To help others know what you're documenting, [open an
51
+
issue](https://github.com/documenting-ruby/ruby/issues/new) on
52
+
documenting-ruby's fork of Ruby.
36
53
37
54
Write your new documentation.
38
55
39
-
- For writing top-level docs in C files, look for `Document-class` or `rb_define_class` (may be towards the bottom of the file.) For writing method docs, look for `rb_define_method`, and then look for the function it uses.
40
-
- To emit `<code>foo.bar</code>`, you can use `+foo.bar+`. It doesn't always work on operators, so use `<code>==</code>`, not `+==+`.
41
-
- Use `#foo` when writing about the foo method - it'll make a link to foo's documentation. `Foo.new(42)` will create a link to the constructor's docs.
56
+
- For writing top-level docs in C files, look for `Document-class` or
57
+
`rb_define_class` (may be towards the bottom of the file.) For writing method
58
+
docs, look for `rb_define_method`, and then look for the function it uses.
59
+
- To emit `<code>foo.bar</code>`, you can use `+foo.bar+`. It doesn't always
60
+
work on operators, so use `<code>==</code>`, not `+==+`.
61
+
- Use `#foo` when writing about the foo method - it'll make a link to foo's
62
+
documentation. `Foo.new(42)` will create a link to the constructor's docs.
42
63
43
64
Generate your new HTML documentation:
44
65
{% highlight bash %}
@@ -52,7 +73,9 @@ rdoc -o tmpdoc lib/drb*
52
73
53
74
Preview your new documentation in `tmpdoc/index.html`.
54
75
55
-
> Tip: You can use the `adsf` gem to serve your files locally, similar to `gem server`. Install the gem and `cd tmpdoc && adsf`. It defaults to port 3000.
76
+
> Tip: You can use the `adsf` gem to serve your files locally, similar to `gem
77
+
> server`. Install the gem and `cd tmpdoc && adsf`. It defaults to
78
+
> port 3000.
56
79
57
80
Once it looks good delete your extra files:
58
81
{% highlight bash %}
@@ -69,19 +92,41 @@ Commit your documentation change:
69
92
git commit -m "adding documentation for WHAT_YOU_CHANGED"
70
93
{% endhighlight %}
71
94
72
-
Submit a pull request to documenting-ruby's fork if you want a quality review, or need help creating a patch to submit to Ruby Core. Or if you have something that's ready to go, you can submit the patch yourself (see instructions below). You should **not** submit a pull request to ruby/ruby, they don't use github's mechanism for this.
95
+
Submit a pull request to documenting-ruby's fork if you want a quality review,
96
+
or need help creating a patch to submit to Ruby Core. Or if you have something
97
+
that's ready to go, you can submit the patch yourself (see instructions below).
73
98
99
+
<aname="CreatePatch"></a>
100
+
<aclass="top"href="#">top</a>
74
101
## Instructions for creating your own patch
75
102
76
103
Create a patch to submit to ruby-core:
77
104
{% highlight bash %}
78
105
git format-patch HEAD~1
79
106
{% endhighlight %}
80
107
81
-
[Open a new ticket](http://redmine.ruby-lang.org/projects/ruby-19/issues/new) on RedMine and submit your patch (will be called something like "0001-\*.patch" in the root directory of the project). You'll need to [sign up](http://redmine.ruby-lang.org/account/register) if you haven't before. Assigning Eric Hodel to the ticket should help make sure your patch is pulled in a timely manner.
108
+
If you're having trouble generating a patch, but you have committed your
109
+
changes to github, simply append `.patch` to the end of your commit. For
you can save this page as a patch and upload it to the bug tracker.
115
+
116
+
[Open a new ticket](http://bugs.ruby-lang.org/projects/ruby-trunk/issues/new)
117
+
on RedMine and submit your patch (will be called something like "0001-\*.patch"
118
+
in the root directory of the project). You'll need to [sign
119
+
up](http://bugs.ruby-lang.org/account/register) if you haven't before.
120
+
Assigning drbrain or zzak to the ticket should help make sure your patch is
121
+
pulled in a timely manner.
82
122
83
123
## Additional Information
84
124
85
-
[Here is](https://github.com/ruby/ruby/commit/071a678a156dde974d8e470b659c89cb02b07b3b) an example of a documentation patch that Eric Hodel added. You can reference this for style.
an example of a documentation patch that Eric Hodel added. You can reference
128
+
this for style.
86
129
87
-
Thanks to [Steve Klabnik](http://steveklabnik.com/) for his [excellent post](http://blog.steveklabnik.com/2011/05/10/contributing-to-ruby-s-documentation.html) on which most of this information is based.
130
+
Thanks to [Steve Klabnik](http://steveklabnik.com/) for his [excellent
Copy file name to clipboardExpand all lines: _posts/2011-10-09-about.markdown
+13-4Lines changed: 13 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -7,9 +7,18 @@ tags:
7
7
8
8
# How This Project Came Into Being
9
9
10
-
The Ruby Documentation Project grew out of a burst of documentation activity -
11
-
[MRI Documentation Week](http://projects.mendicantuniversity.org/doc-week.html) - organized by Mendicant University with the specific intention of enhancing the existing MRI documentation.
10
+
The Ruby Documentation Project grew out of a burst of documentation activity -
- organized by Mendicant University with the specific intention of enhancing
13
+
the existing MRI documentation.
12
14
13
-
In the short period of one week, a good deal of quality documentation was produced. Encouraged by the positive response to this event and seeing that there are still many areas of the documentation that need attention, Gregory Brown, Steve Klabnik and members of the [Mendicant University](http://university.rubymendicant.com) have decided to evolve this documentation drive into an ongoing endeavor.
15
+
In the short period of one week, a good deal of quality documentation was
16
+
produced. Encouraged by the positive response to this event and seeing that
17
+
there are still many areas of the documentation that need attention, Gregory
18
+
Brown, Steve Klabnik and members of the [Mendicant
19
+
University](http://university.rubymendicant.com) have decided to evolve this
20
+
documentation drive into an ongoing endeavor.
14
21
15
-
If you'd like to be a part of this effort, here on this website we've assembled various resources to help you navigate the process of creating and submitting a documentation patch for Ruby.
22
+
If you'd like to be a part of this effort, here on this website we've assembled
23
+
various resources to help you navigate the process of creating and submitting a
Copy file name to clipboardExpand all lines: _posts/2011-10-09-support.markdown
+23-3Lines changed: 23 additions & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -7,14 +7,34 @@ tags:
7
7
8
8
### Mailing List
9
9
10
-
If you have any questions about documentation for which you can't find the answer on this website, then please post them to the **documenting.ruby@librelist.org** mailing list. To sign up, send a first message to documenting.ruby@librelist.org with any subject. This step will trigger an email asking you to confirm your subscription request. To finalize your subscription simply reply to the confirmation email you just received.
10
+
If you have any questions about documentation for which you can't find the
11
+
answer on this website, then please post them to the
12
+
**documenting.ruby@librelist.org** mailing list.
13
+
14
+
To sign up, send a first message to documenting.ruby@librelist.org with any
15
+
subject. This step will trigger an email asking you to confirm your
16
+
subscription request. To finalize your subscription simply reply to the
17
+
confirmation email you just received.
11
18
12
19
### IRC Channel
13
20
14
-
We use the #ruby-core IRC channel on freenode for discussions around MRI documentation. The channel is not very active, but feel free to ping @drbrain (Eric Hodel), @seacreature (Gregory Brown) or @steveklabnik (Steve Klabnik) with any questions.
21
+
We use the #ruby-core IRC channel on freenode for discussions around MRI
22
+
documentation.
23
+
24
+
The channel is not very active, but feel free to ping any of the following
* or <ahref="http://twitter.com/steveklabnik">steveklabnik (Steve Klabnik)</a>
16
31
17
32
### Our Ruby Fork
18
33
19
-
The first step for contributing is to create your own fork of documenting-ruby's [fork of ruby on github](https://github.com/documenting-ruby/ruby). The purpose of this setup is to allow for an internal review process of new documentation contributions. For more details on the exact contribution process, read [How to Document Ruby](/step-by-step-guide.html)
34
+
The first step for contributing is to create your own fork of
35
+
documenting-ruby's [fork of ruby on
36
+
github](https://github.com/documenting-ruby/ruby). The purpose of this setup is
37
+
to allow for an internal review process of new documentation contributions. For
38
+
more details on the exact contribution process, read [How to Document
Copy file name to clipboardExpand all lines: index.html
+2-2Lines changed: 2 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,7 @@
7
7
8
8
<h2>Why Documentation?</h2>
9
9
<ul>
10
-
<li>Only about 60% of Ruby is adequately documented</li>
10
+
<li>Only about 75% of Ruby is adequately documented</li>
11
11
<li>Existing documentation could use some polish in form of clearer descriptions and better examples</li>
12
12
<li>Writing documentation is a gentle, but effective introduction to contributing to open source</li>
13
13
<li>Great way to solidify your Ruby fundamentals</li>
@@ -24,7 +24,7 @@ <h2>What We Provide</h2>
24
24
</ul>
25
25
26
26
<h2>How It Works (In a Nutshell)</h2>
27
-
<p>Generally, Ruby documentation patches need to be submitted to the Redmine <ahref="http://redmine.ruby-lang.org">Ruby Issue Tracking System</a>. We pave the way to ensure a successful submission by setting up an internal review process through Github. To take advantage of this workflow you need to:</p>
27
+
<p>Generally, Ruby documentation patches need to be submitted to the Redmine <ahref="http://bugs.ruby-lang.org">Ruby Issue Tracking System</a>. We pave the way to ensure a successful submission by setting up an internal review process through Github. To take advantage of this workflow you need to:</p>
28
28
29
29
<ol>
30
30
<li>Create your own fork of <ahref="https://github.com/documenting-ruby/ruby">this fork of ruby</a></li>
0 commit comments