Permalink
Browse files

* Added a `require`-able library that injects the generator into RDo…

…c's known

   generator hash.
 * Modified method anchors to be the method name instead of a random number --
   this will break URLs generated by RDoc, but I'd rather have sensible URLs.
 * Added a javascript hook that highlights the current page target if there is one.
 * Updated jQuery to 1.2.4

--HG--
extra : convert_revision : svn%3A8c66a899-4b77-dc11-840b-00304827d434/trunk%4014
  • Loading branch information...
1 parent 56d1648 commit bfd4f11772fc04875b80d47c7d9bb97bace5c5e4 deveiant committed May 21, 2008
View
33 README
@@ -1,24 +1,30 @@
-= Darkfish Rdoc Generator =
+= Darkfish Rdoc Generator
This is a complete replacement for the default HTML generator for Rdoc.
I created it with a few goals in mind:
* Replace the four-frame layout with three different indexes with a single-page,
class/module-focused view.
-* I helped write what became the default look and feel for Rdoc, but it's starting to show its age.
- I wanted to update it with new CSS and Javascript for modern browsers.
+
+* I helped write what became the default look and feel for Rdoc, but it's
+ starting to show its age. I wanted to update it with new CSS and Javascript
+ for modern browsers.
+
* Add some of the nifty searching and index-on-the-side stuff I liked from the
- modified Allison template (<URL:http://www.superalloy.nl/blog/?p=7>) Eloy Duran came up with.
-* Implemented using ERB templates instead of Rdoc's constants-in-a-module style templating.
+ modified Allison template (<URL:http://www.superalloy.nl/blog/?p=7>) Eloy
+ Duran came up with.
-I think I mostly succeeded, and it's nice enough that I wanted to use it for all my documentation,
-and I thought you might want to, too. Or at least be able to tweak it to generate your own spiffy
-docs.
+* Implemented using ERB templates instead of Rdoc's constants-in-a-module style
+ templating.
+
+I think I mostly succeeded, and it's nice enough that I wanted to use it for all
+my documentation, and I thought you might want to, too. Or at least be able to
+tweak it to generate your own spiffy docs.
It looks like this:
- http://deveiate.org/darkfish_preview.png
+http://deveiate.org/darkfish_preview.png
== Getting Started
@@ -32,21 +38,24 @@ Or download the source and do:
== Usage
-To use it, just specify that you want 'darkfish' output instead of the default when you run Rdoc:
+To use it, just specify that you want 'darkfish' output instead of the default
+when you run Rdoc:
- $ rdoc -w 4 -SHN -f *darkfish* -m README README lib
+ $ rdoc -w 4 -SHN -f darkfish -m README README lib
Or from a Rakefile:
### Task: rdoc
require 'rake/rdoctask'
+ gem 'darkfish-rdoc'
+
Rake::RDocTask.new do |rdoc|
rdoc.title = "My Awesome SnoCone Library"
rdoc.options += [
'-w', '4',
'-SHN',
- '-f', 'darkfish',
+ '-f', 'darkfish', # This bit
'-m', 'README',
]
View
@@ -26,6 +26,8 @@ require 'rake/packagetask'
require 'rake/gempackagetask'
require 'pathname'
require 'rbconfig'
+require 'rdoc/generators/darkfish_generator'
+
include Config
@@ -57,8 +59,6 @@ RELEASE_NAME = "REL #{PKG_VERSION}"
RDOC_OPTIONS = [
'-w', '4',
'-SHN',
- '-i', 'docs',
- '-f', 'darkfish',
'-m', 'README',
'-W', 'http://deveiate.org/projects/Darkfish-Rdoc/browser/trunk/'
]
@@ -97,13 +97,13 @@ end
### Task: rdoc
Rake::RDocTask.new do |rdoc|
- rdoc.rdoc_dir = 'rdoc'
- rdoc.title = "Darkfish Rdoc"
+ rdoc.title = "%s - %s" % [ PKG_NAME, PKG_VERSION ]
rdoc.options += RDOC_OPTIONS
+ rdoc.options += [ '-f', 'darkfish' ]
rdoc.rdoc_files.include 'README'
- rdoc.rdoc_files.include LIB_FILES
+ rdoc.rdoc_files.include LIB_FILES.collect {|path| path.to_s }
end
View
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
@@ -0,0 +1,22 @@
+# Bootstrap file for the Darkfish RDoc generator -- since RDoc doesn't
+# know about gems, this file is necessary to get things loaded before RDoc
+# checks to see what generators it knows about.
+
+require 'pathname'
+require 'rdoc/rdoc'
+
+begin
+ generator_dir = Pathname.new( __FILE__ ).dirname + 'rdoc/generators'
+
+ # Add the darkfish generator to the ones RDoc knows about
+ generator = RDoc::RDoc::Generator.new(
+ generator_dir + 'darkfish_generator.rb',
+ :DarkfishGenerator,
+ 'darkfish'
+ )
+ RDoc::RDoc::GENERATORS[ 'darkfish' ] = GENERATOR
+end
+
+
+
+
@@ -36,9 +36,7 @@
require 'erb'
require 'yaml'
-require 'rdoc/options'
-require 'rdoc/markup/simple_markup'
-require 'rdoc/markup/simple_markup/to_html'
+require 'rdoc/rdoc'
require 'rdoc/generators/xml_generator'
### A erb-based RDoc HTML generator
@@ -45,9 +45,19 @@
});
};
+ function highlightTarget() {
+ if ( ! window.location.hash || window.location.hash.length == 0 ) return;
+
+ var anchor = window.location.hash.substring(1);
+ $("a[name=" + anchor + "]").each( function() {
+ $(this).parent().wrap( '<div class="target-section"></div>' );
+ });
+ };
+
$(document).ready( function() {
hookSourceViews();
hookQuickSearch();
+ highlightTarget();
});
</script>
@@ -121,7 +131,8 @@
<h3 class="section-header">Methods</h3>
<ul class="link-list">
<% classinfo['methods'].each do |meth| %>
- <li><a href="<%= meth['aref'] %>"><%= meth['name'] %></a></li>
+ <li><a href="#<%= meth['name'] %>"><%= meth['name']
+ %></a></li>
<% end %>
</ul>
</div>
@@ -184,7 +195,7 @@
<h3 class="section-header">Constants</h3>
<dl>
<% classinfo['sections'].first['constants'].each do |const| %>
- <dt><%= const['name'] %></dt>
+ <dt><a name="<%= const['name'] %>"><%= const['name'] %></a></dt>
<% if const['desc'] %>
<dd class="description"><%= const['desc'].strip %></dd>
<% else %>
@@ -202,6 +213,10 @@
<% classinfo['sections'].first['attributes'].each do |attrib| %>
<div id="<%= attrib['name'].downcase.gsub(/[^a-z]+/, '-') %>-attribute-method" class="method-detail">
+ <a name="<%= attrib['name'] %>"></a>
+ <% if attrib['rw'] =~ /w/i %>
+ <a name="<%= attrib['name'] %>="></a>
+ <% end %>
<div class="method-heading attribute-method-heading">
<span class="method-name"><%= h attrib['name'] %></span><span
class="attribute-access-type">[<%= attrib['rw'] %>]</span>
@@ -227,11 +242,11 @@
<% methodlist['methods'].each do |methodinfo| %>
<% if methodinfo['m_desc'] =~ /Alias for/ %>
- <div id="method-<%= methodinfo['aref'] %>" class="method-detail method-alias">
+ <div id="<%= methodinfo['name'].gsub( /[^a-z]+/, '-' ) %>-method" class="method-detail method-alias">
<% else %>
- <div id="method-<%= methodinfo['aref'] %>" class="method-detail">
+ <div id="<%= methodinfo['name'].gsub( /[^a-z]+/, '-' ) %>-method" class="method-detail">
<% end %>
- <a name="<%= methodinfo['aref'] %>"></a>
+ <a name="<%= methodinfo['name'] %>"></a>
<div class="method-heading">
<span class="method-name"><%= methodinfo['name'] %></span><span
@@ -247,7 +262,8 @@
<% end %>
<% if methodinfo['sourcecode'] %>
- <div class="method-source-code" id="<%= methodinfo['aref'] %>-source">
+ <div class="method-source-code"
+ id="<%= methodinfo['name'].gsub( /[^a-z]+/, '-' ) %>-source">
<pre>
<%= methodinfo['sourcecode'] %>
</pre>

Large diffs are not rendered by default.

Oops, something went wrong.
@@ -1,5 +1,6 @@
/* @override
http://localhost/darkfish/rdoc.css
+ http://gont.ljc.laika.com:3474/manual/api/rdoc.css
*/
/*
@@ -46,6 +47,12 @@ a:hover {
border-bottom: 1px dotted #6C8C22;
}
+pre {
+ background: #ddd;
+ padding: 0.5em 0;
+}
+
+
/* @group Generic Classes */
.quicksearch-field {
@@ -61,10 +68,10 @@ a:hover {
.missing-docs {
font-size: 120%;
- background: #d00 url(images/wrench_orange.png) no-repeat 4px center;
- color: white;
+ background: white url(images/wrench_orange.png) no-repeat 4px center;
+ color: #ccc;
line-height: 2em;
- text-shadow: #151515 2px 2px 1px;
+ border: 1px solid #d00;
opacity: 1;
padding-left: 20px;
text-indent: 24px;
@@ -74,6 +81,13 @@ a:hover {
-moz-border-radius: 5px;
}
+.target-section {
+ border: 2px solid #dcce90;
+ border-left-width: 8px;
+ padding: 0 1em;
+ background: #fff3c2;
+}
+
/* @end */
@@ -225,10 +239,21 @@ ul.link-list .type {
/* @group Documentation Section */
#description {
- font-size: 115%;
+ font-size: 100%;
color: #333;
}
+#description p {
+ margin: 1em 0.4em;
+}
+
+#description ul {
+ margin-left: 2em;
+}
+#description ul li {
+ line-height: 1.4em;
+}
+
#description dl {
margin: 8px 1.5em;
border: 1px solid #ccc;
@@ -377,7 +402,12 @@ div.method-source-code {
overflow: hidden;
}
-div.method-source-code pre { color: white; overflow: hidden; }
+div.method-source-code pre {
+ background: inherit;
+ padding: 0;
+ color: white;
+ overflow: hidden;
+}
/* @group Ruby keyword styles */

0 comments on commit bfd4f11

Please sign in to comment.