Skip to content

Commit 26252a0

Browse files
madebydnamadebydna
committed
added basic website structure and some currently available resources
1 parent 1d3894c commit 26252a0

15 files changed

+615
-16
lines changed

‎.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
.rvmrc
2+
_site

‎README

Lines changed: 0 additions & 16 deletions
This file was deleted.

‎_config.yml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
markdown: rdiscount
2+
pygments: true
3+
root: "/"
4+
author: "Mendicant University alumni"
5+
auto: true
6+
permalink: none

‎_layouts/default.html

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2+
<html xmlns="http://www.w3.org/1999/xhtml">
3+
<head>
4+
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
5+
<title>Ruby Documentation Project</title>
6+
<meta name="keywords" content="ruby, documentation, MRI, rdoc, mendicant university, documentation patch" />
7+
<meta name="description" content="Information site for creating documentation patches for Ruby" />
8+
<link href="/assets/default.css" rel="stylesheet" type="text/css" />
9+
<link href="/assets/syntax.css" rel="stylesheet" type="text/css" />
10+
</head>
11+
<body>
12+
<div id="outer">
13+
<div id="header">
14+
<h1><a href="/">Ruby Documentation Project</a></h1>
15+
<h2>A concerted effort to augment and enhance Ruby MRI documentation</h2>
16+
</div>
17+
<div id="menu">
18+
<ul>
19+
<li class="first"><a href="/" accesskey="1" title="">Home</a></li>
20+
{% for item in site.tags.menu %}
21+
<li><a href="{{item.url}}" accesskey="2">{{ item.title }}</a></li>
22+
{% endfor %}
23+
</ul>
24+
</div>
25+
<div id="content">
26+
<div id="primaryContentContainer">
27+
<div id="primaryContent">
28+
{{ content }}
29+
</div>
30+
</div>
31+
<div id="secondaryContent">
32+
<h3>Get Involved</h3>
33+
<ul>
34+
{% for post in site.tags.help %}
35+
<li><a href="{{ post.url}}">{{ post.title }}</a></li>
36+
{% endfor %}
37+
</ul>
38+
<h3>More Resources</h3>
39+
<ul>
40+
<li>
41+
<a href="http://redmine.ruby-lang.org/projects/ruby/wiki/DocumenterHowTo">Style Guide</a>
42+
</li>
43+
</ul>
44+
</div>
45+
<div class="clear"></div>
46+
</div>
47+
<div id="footer">
48+
<p>Copyright &copy; 2011 Ruby Documentation Project. Design adapted from <a href="http://www.freecsstemplates.org/preview/civilized/">Civilized</a></p>
49+
</div>
50+
</div>
51+
</body>
52+
</html>

‎_layouts/post.html

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2+
<html xmlns="http://www.w3.org/1999/xhtml">
3+
<head>
4+
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
5+
<title>Ruby Documentation Project</title>
6+
<meta name="keywords" content="ruby, documentation, MRI, rdoc, mendicant university, documentation patch" />
7+
<meta name="description" content="Information site for creating documentation patches for Ruby" />
8+
<link href="/assets/default.css" rel="stylesheet" type="text/css" />
9+
<link href="/assets/syntax.css" rel="stylesheet" type="text/css" />
10+
</head>
11+
<body>
12+
<div id="outer">
13+
<div id="header">
14+
<h1><a href="/">Ruby Documentation Project</a></h1>
15+
<h2>A concerted effort to augment and enhance Ruby MRI documentation</h2>
16+
</div>
17+
<div id="menu">
18+
<ul>
19+
<li class="first"><a href="/" accesskey="1" title="">Home</a></li>
20+
{% for item in site.tags.menu %}
21+
<li><a href="{{item.url}}" accesskey="2">{{ item.title }}</a></li>
22+
{% endfor %}
23+
</ul>
24+
</div>
25+
<div id="content">
26+
<div id="primaryContentContainer">
27+
<div id="primaryContent">
28+
<h1>{{ page.title }}</h1>
29+
{{ content }}
30+
</div>
31+
</div>
32+
<div id="secondaryContent">
33+
<h3>Get Involved</h3>
34+
<ul>
35+
{% for post in site.tags.help %}
36+
<li><a href="{{ post.url}}">{{ post.title }}</a></li>
37+
{% endfor %}
38+
</ul>
39+
<h3>More Resources</h3>
40+
<ul>
41+
<li>
42+
<a href="http://redmine.ruby-lang.org/projects/ruby/wiki/DocumenterHowTo">Style Guide</a>
43+
</li>
44+
</ul>
45+
</div>
46+
<div class="clear"></div>
47+
</div>
48+
<div id="footer">
49+
<p>Copyright &copy; 2011 Ruby Documentation Project. Design adapted from <a href="http://www.freecsstemplates.org/preview/civilized/">Civilized</a></p>
50+
</div>
51+
</div>
52+
</body>
53+
</html>

‎_posts/2011-10-07-step-by-step-guide.markdown

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
layout: post
3+
title: "How To Document Ruby"
4+
tags:
5+
- help
6+
---
7+
8+
## Getting Set Up
9+
10+
Fork MU's fork of Ruby [on github](https://github.com/rmu/ruby).
11+
12+
Clone your new repo:
13+
{% highlight bash %}
14+
git clone git@github.com:YOUR_NAME/ruby.git
15+
{% endhighlight %}
16+
17+
Add the upstream remote:
18+
{% highlight bash %}
19+
git remote add upstream https://github.com/rmu/ruby.git
20+
git fetch upstream
21+
git merge upstream/trunk
22+
{% endhighlight %}
23+
24+
Choose some code to document. You can use our [suggestions for code to document](http://projects.mendicantuniversity.org/mri-list.html) or follow these instructions to generate your own list of undocumented code. Check MU's [fork of Ruby issues](https://github.com/rmu/ruby/issues) for a list of documentation other people are working on.
25+
26+
Get a list of undocumented code (you must have rdoc >= 3.3 for this to work):
27+
{% highlight bash %}
28+
rdoc -C1 > documentation_coverage.txt
29+
{% endhighlight %}
30+
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.
32+
33+
## Documenting
34+
35+
To help others know what you're documenting, [open an issue](https://github.com/rmu/ruby/issues/new) on MU's fork of Ruby.
36+
37+
Write your new documentation.
38+
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.
42+
43+
Generate your new HTML documentation:
44+
{% highlight bash %}
45+
rdoc -o tmpdoc PATH/TO/YOUR/FILES
46+
{% endhighlight %}
47+
48+
This for example will document all `drb` files:
49+
{% highlight bash %}
50+
rdoc -o tmpdoc lib/drb*
51+
{% endhighlight %}
52+
53+
Preview your new documentation in `tmpdoc/index.html`.
54+
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&nbsp;3000.
56+
57+
Once it looks good delete your extra files:
58+
{% highlight bash %}
59+
rm -rf tmpdoc documentation_coverage.txt
60+
{% endhighlight %}
61+
62+
Add your documentation change:
63+
{% highlight bash %}
64+
git add .
65+
{% endhighlight %}
66+
67+
Commit your documentation change:
68+
{% highlight bash %}
69+
git commit -m "adding documentation for WHAT_YOU_CHANGED"
70+
{% endhighlight %}
71+
72+
Submit a pull request to MU'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.
73+
74+
## Instructions for creating your own patch
75+
76+
Create a patch to submit to ruby-core:
77+
{% highlight bash %}
78+
git format-patch HEAD~1
79+
{% endhighlight %}
80+
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.
82+
83+
## Additional Information
84+
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.
86+
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.

‎_posts/2011-10-07-undocumented-areas.markdown

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
layout: post
3+
title: "List of Undocumented Areas"
4+
tags:
5+
- help
6+
---
7+
8+
Many modules in Ruby lack a basic top-level description of what they do. In many cases, this is a relatively easy task to do. What is needed is one or two paragraphs of description, and a couple of realistic examples of its use.
9+
10+
### Example of well documented classes
11+
12+
- [OpenSSL](https://github.com/rmu/ruby/blob/trunk/ext/openssl/ossl.c#L418-790)
13+
- [BasicObject](https://github.com/rmu/ruby/blob/trunk/object.c#L2618-2669)
14+
15+
### Classes/Modules which lack documentation
16+
17+
- Debug
18+
- Encoding
19+
- Fiddle
20+
- IRB*
21+
- Mkmf
22+
- Monitor::MonitorMixin
23+
- Mutex_m
24+
- Profile, Profiler
25+
- Random
26+
- Range
27+
- RbConfig
28+
- RSS
29+
- Shell
30+
- Thread
31+
32+
### Classes/Modules with poor documentation
33+
34+
- ARGF
35+
- Array
36+
- CMath need clarifications (Complex is now in core, what does it do now?)
37+
- Digest: no examples (Digest::MD5 is not even in the class list)
38+
- Enumerable
39+
- Etc
40+
- Float
41+
- Hash
42+
- PTY
43+
- Racc
44+
- Rinda
45+
- Sync, Sync_m
46+
- Time
47+
- ZLib
48+
49+
### More specialized things
50+
51+
- initialize_copy
52+
- Object#hash
53+
54+
55+
### Some other tips for finding areas to document
56+
57+
- Look near `Init_<class name>` in `<class_name>.c`
58+
59+
- [List of class-level documentation by byte length](https://gist.github.com/1254953). Low numbers don't necessarily mean poor documentation, but if you see a much-used class low on the list, it may be a candidate for improvement.
60+

‎_posts/2011-10-09-about.markdown

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
layout: default
3+
title: "About This Project"
4+
tags:
5+
- menu
6+
---
7+
8+
Info about how Mendicant Doc Week evolved into an ongoing effort to increase the MRI Documentation coverage.

‎_posts/2011-10-09-contact.markdown

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
layout: default
3+
title: "Contact Us"
4+
tags:
5+
- menu
6+
---
7+
8+
Who to contact and how.

‎assets/a1.jpg

14.4 KB
Loading

‎assets/a2.gif

4.02 KB
Loading

‎assets/a4.gif

3.59 KB
Loading

0 commit comments

Comments
 (0)