From fb93b80b59cf2c3d8e828741d1b73bdf23c36233 Mon Sep 17 00:00:00 2001 From: Tobie Langel Date: Wed, 23 Dec 2009 06:32:59 +0100 Subject: [PATCH 1/6] doc: using pygments for syntax highlighting. --- Rakefile | 3 +- .../html/assets/stylesheets/pygments.css | 195 ++++++++++++++++++ templates/html/layout.erb | 4 +- vendor/pdoc | 2 +- 4 files changed, 200 insertions(+), 4 deletions(-) create mode 100644 templates/html/assets/stylesheets/pygments.css diff --git a/Rakefile b/Rakefile index b6b3a37..b4b03d8 100755 --- a/Rakefile +++ b/Rakefile @@ -75,7 +75,8 @@ module PrototypeHelper PDoc::Runner.new(temp_path, { :output => DOC_DIR, :templates => File.join(TEMPLATES_DIR, "html"), - :index_page => 'README.markdown' + :index_page => 'README.markdown', + :syntax_highlighter => :pygments }).run rm_rf temp_path diff --git a/templates/html/assets/stylesheets/pygments.css b/templates/html/assets/stylesheets/pygments.css new file mode 100644 index 0000000..0857737 --- /dev/null +++ b/templates/html/assets/stylesheets/pygments.css @@ -0,0 +1,195 @@ +.highlight { + background: #fff; +} +.highlight .c { + color: #998; + font-style: italic; +} +.highlight .err { + color: #a61717; + background-color: #e3d2d2; +} +.highlight .k { + font-weight: bold; +} +.highlight .o { + font-weight: bold; +} +.highlight .cm { + color: #998; + font-style: italic; +} +.highlight .cp { + color: #999; + font-weight: bold; +} +.highlight .c1 { + color: #998; + font-style: italic; +} +.highlight .cs { + color: #999; + font-weight: bold; + font-style: italic; +} +.highlight .gd { + color: #000; + background-color: #fdd; +} +.highlight .gd .x { + color: #000; + background-color: #faa; +} +.highlight .ge { + font-style: italic; +} +.highlight .gr { + color: #a00; +} +.highlight .gh { + color: #999; +} +.highlight .gi { + color: #000; + background-color: #dfd; +} +.highlight .gi .x { + color: #000; + background-color: #afa; +} +.highlight .go { + color: #888; +} +.highlight .gp { + color: #555; +} +.highlight .gs { + font-weight: bold; +} +.highlight .gu { + color: #aaa; +} +.highlight .gt { + color: #a00; +} +.highlight .kc { + font-weight: bold; +} +.highlight .kd { + font-weight: bold; +} +.highlight .kp { + font-weight: bold; +} +.highlight .kr { + font-weight: bold; +} +.highlight .kt { + color: #458; + font-weight: bold; +} +.highlight .m { + color: #099; +} +.highlight .s { + color: #d14; +} +.highlight .na { + color: #008080; +} +.highlight .nb { + color: #0086B3; +} +.highlight .nc { + color: #458; + font-weight: bold; +} +.highlight .no { + color: #008080; +} +.highlight .ni { + color: #800080; +} +.highlight .ne { + color: #900; + font-weight: bold; +} +.highlight .nf { + color: #900; + font-weight: bold; +} +.highlight .nn { + color: #555; +} +.highlight .nt { + color: #000080; +} +.highlight .nv { + color: #008080; +} +.highlight .ow { + font-weight: bold; +} +.highlight .w { + color: #bbb; +} +.highlight .mf { + color: #099; +} +.highlight .mh { + color: #099; +} +.highlight .mi { + color: #099; +} +.highlight .mo { + color: #099; +} +.highlight .sb { + color: #d14; +} +.highlight .sc { + color: #d14; +} +.highlight .sd { + color: #d14; +} +.highlight .s2 { + color: #d14; +} +.highlight .se { + color: #d14; +} +.highlight .sh { + color: #d14; +} +.highlight .si { + color: #d14; +} +.highlight .sx { + color: #d14; +} +.highlight .sr { + color: #009926; +} +.highlight .s1 { + color: #d14; +} +.highlight .ss { + color: #990073; +} +.highlight .bp { + color: #999; +} +.highlight .vc { + color: #008080; +} +.highlight .vg { + color: #008080; +} +.highlight .vi { + color: #008080; +} +.highlight .il { + color: #099; +} diff --git a/templates/html/layout.erb b/templates/html/layout.erb index 6e6aed8..8624389 100644 --- a/templates/html/layout.erb +++ b/templates/html/layout.erb @@ -7,10 +7,10 @@ <%= javascript_include_tag "prototype" %> - <%= javascript_include_tag "application", "code_highlighter", "tabs" %> + <%= javascript_include_tag "application", "tabs" %> <%= javascript_include_tag "item_index" %> - <%= stylesheet_link_tag "api" %> + <%= stylesheet_link_tag "api", "pygments" %> - - - - - - -
-
-
-

- Prototype JavaScript framework -

-
-
-
- - <%= @content_for_layout %> - -
- - - -
- - diff --git a/templates/html/namespace.erb b/templates/html/namespace.erb deleted file mode 100644 index 5e57256..0000000 --- a/templates/html/namespace.erb +++ /dev/null @@ -1,171 +0,0 @@ -<% d = @doc_instance %> - -<% @title = "#{d.full_name} #{d.type}" %> - -<%= include "partials/breadcrumbs", :object => d %> - -

- <%= d.type %> <%= d.full_name %> -

- -<% # Does it have a description? %> - -<% if d.description && !d.description.empty? %> -
- -
-

Description

-
- -
- <%= htmlize(d.description) %> -
- -
-<% end %> - -<% # Is it a CLASS? %> -<% if d.is_a?(Documentation::Klass) %> - - <% if d.superklass %> -
-
-

Superclass

-
- -
-

<%= auto_link_code(d.superklass, false) %>

-
-
- <% end %> - - <% unless d.subklasses.empty? %> -
-
-

Subclasses

-
- -
-

<%= d.subklasses.map { |s| auto_link_code(s, false) }.join(', ') %>

-
-
- <% end %> - -<% end %> - -<% # Does it have MIXINS? %> -<% unless d.mixins.compact.empty? %> -
-
-

Includes

-
- -
-

<%= d.mixins.map { |m| auto_link_code(m, false) }.join(', ') %>

-
-
-<% end %> - -<% # Are there related utilities? %> -<% unless d.related_utilities.empty? %> -
-
-

Related utilities

-
- -
-

<%= d.related_utilities.map { |u| auto_link_code(u, false) }.join(', ') %>

-
-
-<% end %> - -<% # List its methods. %> -<% unless d.all_methods.empty? && d.mixins.empty? %> -
-
-

Methods

-
- -
-
    - <% d.all_methods.each do |method| %> -
  • <%= auto_link_code(method, true, :class => class_names_for(method)) %>
    • - <% end %> -
- - <% unless d.mixins.compact.empty? %> - <% d.mixins.each do |mixin| %> -

Inherited from <%= auto_link(mixin) %>

-
    - <% mixin.all_methods.each do |method| %> -
  • <%= auto_link_code(method, true, :class => class_names_for(method)) %>
    • - <% end %> -
- <% end %> - <% end %> - - -
- -
-<% end %> - -<% if d.is_a?(Documentation::Klass) && d.constructor %> -
-
-

Constructor

-
- -
- 
<%= d.constructor.ebnf_expressions.join("\n").strip %>
- <% unless d.constructor.arguments.empty? %> -
    - <% d.constructor.arguments.each do |arg| %> -
  • - <%= arg.name %> - <% unless arg.types.empty? %> - (<%= arg.types.map { |t| auto_link_code(t, false) }.join(' | ') %>) - <% end %> - <%= ' – ' + inline_htmlize(arg.description) unless arg.description.empty? %> -
    • - <% end %> -
- <% end %> - - -

<%= htmlize(d.constructor.description) %>

- -
- -
-<% end %> - - -<% -types = { - :constants => "Constants", - :klass_methods => "Class methods", - :klass_properties => "Class properties", - :instance_methods => "Instance methods", - :instance_properties => "Instance properties" -} -%> - -<% types.each do |method, title| %> - <% methods = d.send(method) %> - <% unless methods.empty? %> -
- -
-

<%= title %>

-
- -
-
    - <%= include "partials/short_description", :collection => methods %> -
- -
-
- <% end %> -<% end %> \ No newline at end of file diff --git a/templates/html/partials/breadcrumbs.erb b/templates/html/partials/breadcrumbs.erb deleted file mode 100644 index 7e02719..0000000 --- a/templates/html/partials/breadcrumbs.erb +++ /dev/null @@ -1,6 +0,0 @@ - \ No newline at end of file diff --git a/templates/html/partials/short_description.erb b/templates/html/partials/short_description.erb deleted file mode 100644 index c4ad784..0000000 --- a/templates/html/partials/short_description.erb +++ /dev/null @@ -1,48 +0,0 @@ -
  • -

    <%= object.name %> - #

    - - <% if object.signature %> - <%= method_synopsis(object) %> - <% end %> - - <% if object.is_a?(Documentation::Method) %> - <% unless object.arguments.empty? %> - - <% end %> - <% end %> - - <%= htmlize(object.description) %> - - <% # Does it have an alias? %> - <% unless object.aliases.empty? %> -

    Aliased as: <%= object.aliases.map { |a| auto_link_code(a, false) }.join(', ') %>

    - <% end %> - - <% # Is it an alias of something else? %> - <% if object.alias? %> -

    Alias of: <%= auto_link_code(object.alias_of, false) %>

    - <% end %> - - <% # Is it related to something? %> - <% if object.is_a?(Documentation::Utility) && object.related_to %> -

    Related to: - <%= auto_link_code(object.related_to, false) %>

    - <% end %> - - <% # Is it methodized? %> - <% if object.is_a?(Documentation::Method) && object.methodized? %> -

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

    - <% end %> - -
    • diff --git a/templates/html/section.erb b/templates/html/section.erb deleted file mode 100644 index f433573..0000000 --- a/templates/html/section.erb +++ /dev/null @@ -1,99 +0,0 @@ -<% @title = "#{@doc_instance.full_name}" %> -<% section = @doc_instance %> - -<%= include "partials/breadcrumbs", :object => section %> - -

    - Section <%= section.name %> -

    - -
    - -
    -

    Description

    -
    - -
    - <%= htmlize(section.description) %> -
    - -
    - -<% # Iterate over the items in this section. %> - -<% utilities = section.utilities %> -<% unless utilities.empty? %> - -
    -
    -

    Utilities

    -
    - -
    -
      - <% utilities.each do |utility| %> -
    • <%= auto_link_code(utility) %>
      • - <% end %> -
    -
    -
    - -<% end %> - -<% namespaces = section.namespaces %> -<% unless namespaces.empty? %> - -
    -
    -

    Namespaces

    -
    - -
    -
      - <% namespaces.each do |namespace| %> -
    • -

      - <%= namespace.full_name %> -

      - - <% unless namespace.short_description.nil? %> -

      <%= htmlize(namespace.short_description) %>

      - <% end %> - -
      • - <% end %> -
    -
    -
    - -<% end %> - -<% klasses = section.klasses %> -<% unless klasses.empty? %> - -
    - -
    -

    Classes

    -
    - -
    -
      - <% klasses.each do |klass| %> -
    • -

      - <%= klass.full_name %> -

      - - <% unless klass.short_description.nil? %> -

      <%= htmlize(klass.short_description) %>

      - <% end %> - -
      • - <% end %> -
    -
    - -
    - -<% end %> \ No newline at end of file diff --git a/templates/html/utility.erb b/templates/html/utility.erb deleted file mode 100644 index 3ffc98d..0000000 --- a/templates/html/utility.erb +++ /dev/null @@ -1,21 +0,0 @@ -<% d = @doc_instance %> - -<% @title = "#{@doc_instance.full_name} utility" %> - -<%= include "partials/breadcrumbs", :object => d %> - -

    - utility <%= @doc_instance.name %> -

    - -
    -
    -

    Description

    -
    - -
    -
      - <%= include "partials/short_description", :collection => [@doc_instance] %> -
    -
    -
    \ No newline at end of file diff --git a/vendor/pdoc b/vendor/pdoc index 525737c..e429027 160000 --- a/vendor/pdoc +++ b/vendor/pdoc @@ -1 +1 @@ -Subproject commit 525737c9e8696210463edfb4a855e01f39fb25ec +Subproject commit e4290279a1d42bc02b09b234291a2d05c0134a43 From 2e3e02d92c06803bfdedf0ba73dc53d42efc5880 Mon Sep 17 00:00:00 2001 From: Tobie Langel Date: Thu, 24 Dec 2009 03:19:14 +0100 Subject: [PATCH 3/6] doc: Fix documentation errors in Ajax.Response. --- src/ajax/response.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/ajax/response.js b/src/ajax/response.js index 658df87..18cd8ba 100644 --- a/src/ajax/response.js +++ b/src/ajax/response.js @@ -121,7 +121,7 @@ Ajax.Response = Class.create({ }, /** - * Ajax.Response.getResponseHeader(name) -> String + * Ajax.Response#getResponseHeader(name) -> String * * Returns the value of the requested header if present; throws an error * otherwise. This is just a wrapper around the `XmlHttpRequest` method of @@ -132,7 +132,7 @@ Ajax.Response = Class.create({ }, /** - * Ajax.Response.getAllResponseHeaders() -> String + * Ajax.Response#getAllResponseHeaders() -> String * * Returns a string containing all headers separated by line breaks; throws * an error if no headers exist. This is just a wrapper around the From 8a8af0a729487a7f69874ea00074e3e931e8b215 Mon Sep 17 00:00:00 2001 From: Tobie Langel Date: Thu, 24 Dec 2009 07:32:32 +0100 Subject: [PATCH 4/6] doc: Fix documentation for Template. --- src/lang/template.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/lang/template.js b/src/lang/template.js index 8b396a8..fce8476 100644 --- a/src/lang/template.js +++ b/src/lang/template.js @@ -82,14 +82,14 @@ * inadequate, there's a provision for customization. `Template`'s * constructor accepts an optional second argument that is a regular expression * object to match the replaceable symbols in the template string. Let's put - * together a template that uses a syntax similar to the ubiquitous `<&= %>` + * together a template that uses a syntax similar to the ubiquitous `<%= %>` * constructs: * - * // matches symbols like '<&= field %>' + * // matches symbols like '<%= field %>' * var syntax = /(^|.|\r|\n)(\<%=\s*(\w+)\s*%\>)/; * * var t = new Template( - * '
    Name: <&= name %>, Age: <&=age%>
    ', + * '
    Name: <%= name %>, Age: <%= age %>
    ', * syntax); * t.evaluate( {name: 'John Smith', age: 26} ); * // ->
    Name: John Smith, Age: 26
    From 4cc67f2e8e2a47b0c4e681ce9cda0374e6647997 Mon Sep 17 00:00:00 2001 From: Tobie Langel Date: Tue, 29 Dec 2009 01:53:16 +0100 Subject: [PATCH 5/6] doc: Minor cleanup. --- src/dom/dom.js | 6 +++--- src/dom/event.js | 3 ++- src/dom/form.js | 16 ++++++++-------- src/dom/selector.js | 2 +- 4 files changed, 14 insertions(+), 13 deletions(-) diff --git a/src/dom/dom.js b/src/dom/dom.js index 7f0c054..e0daa1d 100644 --- a/src/dom/dom.js +++ b/src/dom/dom.js @@ -1,6 +1,6 @@ /** section: DOM, related to: Element * $(id) -> Element - * $(id...) -> [Element]... + * $(id...) -> [Element...] * - id (String | Element): A DOM node or a string that references a node's * ID. * @@ -2281,8 +2281,8 @@ Element.addMethods = function(methods) { Element.cache = { }; }; -/** section: DOM - * document.viewport +/** + * document.viewport * * The `document.viewport` namespace contains methods that return information * about the viewport — the rectangle that represents the portion of a web diff --git a/src/dom/event.js b/src/dom/event.js index d52c1da..3c28a81 100644 --- a/src/dom/event.js +++ b/src/dom/event.js @@ -621,6 +621,7 @@ * ...and then to remove: * * $('foo').stopObserving('click', this.boundHandlerMethod); // <== Right + * **/ function stopObserving(element, eventName, handler) { element = $(element); @@ -744,7 +745,7 @@ }); /** section: DOM - * document + * document * * Prototype extends the built-in `document` object with several convenience * methods related to events. diff --git a/src/dom/form.js b/src/dom/form.js index 8b8d9c1..1dc1deb 100644 --- a/src/dom/form.js +++ b/src/dom/form.js @@ -248,7 +248,7 @@ Form.Methods = { /*--------------------------------------------------------------------------*/ -/** section: DOM +/** * Form.Element * * Utilities for dealing with form controls in the DOM. @@ -359,7 +359,7 @@ Form.Element.Methods = { }, /** - * Form.Element#activate(element) -> Element + * Form.Element.activate(@element) -> Element * * Gives focus to a form control and selects its contents if it is a text * input. @@ -479,7 +479,7 @@ Form.Element.Serializers = { * Abstract **/ -/** section: DOM +/** * class Abstract.TimedObserver * * An abstract DOM element observer class, subclasses of which can be used to periodically @@ -528,7 +528,7 @@ Abstract.TimedObserver = Class.create(PeriodicalExecuter, { } }); -/** section: DOM +/** * class Form.Element.Observer < Abstract.TimedObserver * * An [[Abstract.TimedObserver]] subclass that watches for changes to a form field's value. @@ -551,7 +551,7 @@ Form.Element.Observer = Class.create(Abstract.TimedObserver, { } }); -/** section: DOM +/** * class Form.Observer < Abstract.TimedObserver * * An [[Abstract.TimedObserver]] subclass that watches for changes to a form. @@ -577,7 +577,7 @@ Form.Observer = Class.create(Abstract.TimedObserver, { /*--------------------------------------------------------------------------*/ -/** section: DOM +/** * class Abstract.EventObserver **/ Abstract.EventObserver = Class.create({ @@ -619,7 +619,7 @@ Abstract.EventObserver = Class.create({ } }); -/** section: DOM +/** * class Form.Element.EventObserver < Abstract.EventObserver **/ Form.Element.EventObserver = Class.create(Abstract.EventObserver, { @@ -628,7 +628,7 @@ Form.Element.EventObserver = Class.create(Abstract.EventObserver, { } }); -/** section: DOM +/** * class Form.EventObserver < Abstract.EventObserver **/ Form.EventObserver = Class.create(Abstract.EventObserver, { diff --git a/src/dom/selector.js b/src/dom/selector.js index 397f45f..0804337 100644 --- a/src/dom/selector.js +++ b/src/dom/selector.js @@ -1,4 +1,4 @@ -/** related to: Prototype.Selector +/** section: DOM, related to: Prototype.Selector * $$(expression...) -> [Element...] * * Returns all elements in the document that match the provided CSS selectors. From 6c1790ac4e6a857742e8fdc761e6305a14c79a17 Mon Sep 17 00:00:00 2001 From: Tobie Langel Date: Tue, 29 Dec 2009 01:54:56 +0100 Subject: [PATCH 6/6] doc: Fix Template doc to avoid issues with Sprockets. --- src/lang/template.js | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/lang/template.js b/src/lang/template.js index fce8476..f9773f5 100644 --- a/src/lang/template.js +++ b/src/lang/template.js @@ -82,14 +82,14 @@ * inadequate, there's a provision for customization. `Template`'s * constructor accepts an optional second argument that is a regular expression * object to match the replaceable symbols in the template string. Let's put - * together a template that uses a syntax similar to the ubiquitous `<%= %>` + * together a template that uses a syntax similar to the now ubiquitous `{{ }}` * constructs: * - * // matches symbols like '<%= field %>' - * var syntax = /(^|.|\r|\n)(\<%=\s*(\w+)\s*%\>)/; + * // matches symbols like '{{ field }}' + * var syntax = /(^|.|\r|\n)(\{{\s*(\w+)\s*}})/; * * var t = new Template( - * '
    Name: <%= name %>, Age: <%= age %>
    ', + * '
    Name: {{ name }}, Age: {{ age }}
    ', * syntax); * t.evaluate( {name: 'John Smith', age: 26} ); * // ->
    Name: John Smith, Age: 26