Notification of upcoming changes
Christophe Porteneuve
I started working on PDoc--at long last--during the first Prototype
Hackfest, held last mid-July in Vienna.
On this occasion, I forked Tobie's master on GitHub and implemented the
following changes, which are scheduled now for inclusion back in the ref
master (therefore, you should be aware of them in advance):
The main change is about methodized methods: Andrew's first jab
requested the syntax to be instance-based, but that didn't make too much
sense (no offense, Andrew! You were sitting right next to me when we
switched that) as you'll be using the "static" variant when providing
the element argument explicitly.
So now, declaring a methodized method requires static signature instead
of instance signature:
RIGHT: Element.show(@element)
WRONG: Element#show(@element)
The helper also outputs two EBNFs for this now: the static one and the
instance-based one. Any further elements in the argument list will be
properly displayed in those.
Other changes focus on the HTML helper:
• known types in structured returns (alternative-based, array-based…)
are detected and auto-linked (it used to be auto-linked on just-a-
simple-type returns only).
• three-dot ellipses ("...") are turned into typographical ellipses
("…").
• Whenever your PDoc provides multiple EBNF's, *we use them*; just
now the ref master will only use the first one; we fixed that to
leverage all the EBNFs comments provide. When on a methodized
method, use the methodized syntax on the *first* EBNF, and go
whichever way you want (instance or static) on the next ones.
You can check the upcoming implementation on my fork [1]; comments are
welcome, either as Git commenting or in this list (or both).
Cheers!
[1] http://github.com/tdd/pdoc/tree/master
--
Christophe Porteneuve aka TDD
t...@tddsworld.com
Tobie Langel
If there's no objection, I'll pull those changes in asap.
Best,
Tobie
Tobie Langel
Tobie Langel
Could you please look into your recent changes to auto_link (http://
github.com/tobie/pdoc/blob/8636c3fc7e0f0279a5a61fbd8b0db58c576403ca/
templates/html/helpers.rb#L81).
There are issues with how it renders certain cases, there are now
occurrences of double slashes as in: "/language//object.html".
I tried debugging its now very difficult to do so. Are five
occurrences of obj.is_a?(String) really necessary?Can you have a
look ?
Tobie
On Aug 12, 3:05 am, Tobie Langel <tobie.lan...@gmail.com> wrote:
> Committed here:http://github.com/tobie/pdoc/commit/8636c3fc7e0f0279a5a61fbd8b0db58c5...
Andrew Dupont
instance, Form.Element#getValue is instead showing up as
Form#Element.getValue. (Of course, it might have been doing this
_before_ your fixes, too.)
Cheers,
Andrew
Christophe Porteneuve
> Christophe,
>
> Could you please look into your recent changes to auto_link (http://
> github.com/tobie/pdoc/blob/8636c3fc7e0f0279a5a61fbd8b0db58c576403ca/
> templates/html/helpers.rb#L81).
>
> There are issues with how it renders certain cases, there are now
> occurrences of double slashes as in: "/language//object.html".
>
> I tried debugging its now very difficult to do so. Are five
> occurrences of obj.is_a?(String) really necessary?Can you have a
> look ?
Hey!
I'll try and look into that this weekend. Just FMI, did these specific
pages work alright *before* my changes?
I'll try and look into the long-pending utility function pages' bugs,
too (they don't create proper relpaths to the assets, hence show up w/o
CSS or JS…).
Andrew Dupont
On Aug 21, 2009, at 4:45 PM, Christophe Porteneuve wrote:
> I'll try and look into the long-pending utility function pages' bugs,
> too (they don't create proper relpaths to the assets, hence show up
> w/o
> CSS or JS…).
Keep in mind: that's something that happens on api.prototypejs.org,
but not on my local machine. I've occasionally tried to push newer
docs to that site, but the newer stuff never shows up; I need to get
Sam to restart that server or something.
Are you still experiencing this bug locally?
Cheers,
Andrew
Tobie Langel
> pages work alright *before* my changes?
The double slashes no. But I don't think those were originally linked.
However, now that they are, they might as well be correctly linked.
I'm more concerned with the overall code quality of those commits, though.
It's hard to understand what these methods are doing, what kind of
arguments they accept, etc.
Christophe Porteneuve
especially *prior* to its being merged upstream :-)
I can't seem to remember how to sync my fork's master with your recent
commits on yours? Do I need to setup some special branch or sth?
Tobie Langel
Yeah, we're definitely lacking a good code review tool.
James Coglan
Yeah, we're definitely lacking a good code review tool.
> I'm more than willing to discuss issues with the quality of my code especially *prior* to its being merged upstream :-)
Possibly related to the above: code auto-linking seems to have broken recently. Was this deliberate, and does anyone have a problem with me applying this:
diff --git a/lib/pdoc/generators/html/helpers.rb b/lib/pdoc/generators/html/help
index 07df8a9..d6ea858 100644
--- a/lib/pdoc/generators/html/helpers.rb
+++ b/lib/pdoc/generators/html/helpers.rb
@@ -21,7 +21,8 @@ module PDoc
end
def htmlize(markdown)
- RDiscount.new(markdown, :smart).to_html
+ html = RDiscount.new(markdown, :smart).to_html
+ html.gsub(/<code>(.*?)<\/code>/) { |match| auto_link_code($1) }
end
# Gah, what an ugly hack.
--
James Coglan
http://jcoglan.com
Tobie Langel
Sorry I took so long to get back to you.
The state of helper.rb is so bad I don't really know how to answer you.
Hopefully I'll find time to clean it up at some point (unless someone
volunteers before then).
Not directly related, but affecting the same lines of code: we'll have
to either switch back to BlueCloth or use Maruku as RDiscount isn't
supported on Windows.
Best,
Tobie
James Coglan
Hi, James.
Sorry I took so long to get back to you.
The state of helper.rb is so bad I don't really know how to answer you.
Agreed, perhaps we start by using named constants for all those regexps -- it's pretty hard to understand right now. Hope you don't mind if I push my autolinking change in for now just to tide me over until we refactor -- I find it really useful for checking my docs for typos, incorrect references etc.
Btw the change you made to allow optional custom helpers was a good move -- probably better for making sure people get automatic updates to the core helpers in the gem if they're using custom templates.
Not directly related, but affecting the same lines of code: we'll have
to either switch back to BlueCloth or use Maruku as RDiscount isn't
supported on Windows.
We can probably handle this the same way we handle ERB vs. Erubis -- try to load all of them, catch LoadErrors, and provide a helper function that hides which one is actually being used. I might have time to look at that next week.
Regards,
James
Tobie Langel
> autolinking change in for now just to tide me over until we refactor -- I
> find it really useful for checking my docs for typos, incorrect references
> etc.
Please go ahead.
> We can probably handle this the same way we handle ERB vs. Erubis -- try to
> load all of them, catch LoadErrors, and provide a helper function that hides
> which one is actually being used.
That's what we were initially doing. However, this causes
inconsistencies in the HTML output depending on which parser is used.
I'd rather we traded performance for consistency here. Especially
since this clearly isn't our perf bottleneck.
Maruku seems like a fair compromise.
I'll push it in once you've done your changes.
Best,
Tobie
Andrew Dupont
On Aug 27, 2009, at 8:07 AM, Tobie Langel wrote:
> That's what we were initially doing. However, this causes
> inconsistencies in the HTML output depending on which parser is used.
>
> I'd rather we traded performance for consistency here. Especially
> since this clearly isn't our perf bottleneck.
>
> Maruku seems like a fair compromise.
Actually, we can move back to BlueCloth, I think — the latest version
integrated the Discount library and is much faster.
Cheers,
Andrew
Tobie Langel
Andrew Dupont
Tobie Langel
T.J. Crowder
I only had time for a two-minute test, but on Windows using an
otherwise fully-functioning One Click Ruby Install setup, this does
not work:
gem install bluecloth
It fails to find tools it wants, like a compiler. :-) If I try it
again with paths and such set up to use Visual Studio 2005's C++
compiler (which I installed trying to get rdiscount to work), it fails
in a variety of other ways.
This is very similar to how rdiscount fails.
Again, though, this was just a very quick test. It may be that with
the right combo of tools (gcc, for instance, on a full cygwin install
rather than something minimalist), it may work. But it is definitely
raising the requirements bar somewhere.
FWIW,
--
T.J. Crowder
tj / crowder software / com