Thanks for an awesome project

[Eric Cunningham]

Hi:

I just discovered YARD and its really cool.  After a little hacking, I used it to put up my website:

http://visualruby.net

Does that look familiar?

I was thinking about making a GUI for it.  It seems like YARD has many options, so having a GUI would really simplify things.  Also, I wanted to change the colors and fonts, and it would be pretty easy to make that happen.

I'm thinking that making a css generating class could hold a "theme" with colors and fonts etc.  Each instance of that class could be saved as a yaml file and exported to the common.css file.  Of course you would work with the yaml file for edits and never mess around with directly editing css (nightmare).

What do you think?

Thanks for the great work.

Eric 

[Loren Segal]

Hey Eric,

That seems like a very cool idea. I'd be interested to look at it when it's done!

Loren

--

---
You received this message because you are subscribed to the Google Groups "YARD" group.
To unsubscribe from this group and stop receiving emails from it, send an email to yardoc+un...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Eric Cunningham]

Hi Loren:

Thanks!  I like yard so much that I'm integrating it into visualruby.

I've written most of the GUI.  It can change the colors and fonts and several sizes of things.  It really adds a huge amount of options to the appearance of the docs.

Also, yard has many command line options that are easily handled with a GUI.

I'll be able to show it to you in a few days.  It will have "themes" of colors and styles, but I'm having trouble with the layouts using templates.

I've read your docs on templates, and I can get most of it to work, but I can't figure out how the frames.html file is generated.  

I've hacked a solution for my own personal website, but I'd like to offer a 3 column option in the GUI.  

I can't understand this:

in templates/fulldoc/frames.erb

<script type="text/javascript" charset="utf-8">

  var match = unescape(window.location.hash).match(/^#!(.+)/);

  var name = match ? match[1] : '<%= url_for_main %>';

  name = name.replace(/^(\w+):\/\//, '').replace(/^\/\//, '');

  window.top.location = name;

</script>

TURNS INTO THIS:

frames.html:

<script type="text/javascript" charset="utf-8">

window.onload = function() {

  var match = unescape(window.location.hash).match(/^#!(.+)/);

  var name = match ? match[1] : 'index.html';

  name = name.replace(/^(\w+):\/\//, '').replace(/^\/\//, '');

  document.writeln('<frameset cols="20%,*">' +

    '<frame name="list" src="class_list.html" />' +

    '<frame name="main" src="' + escape(name) + '" />' +

    '</frameset>');

}

</script>

I've been grepping for everything in this.  Where does it come from?  How can I customize it?

I hope that you'll take the time to point me in the right direction.

Thanks for all your great work.

Yours,

Eric

[Loren Segal]

You should probably check the master branch of YARD if you're writing new templates. frames.html is gone from the next release (as are the <frame> tags). That said, the old frames.erb should have the document.writeln line in it:

https://github.com/lsegal/yard/blob/v0.8.7.6/templates/default/fulldoc/html/frames.erb

Loren

[Eric Cunningham]

Hi Loren:

Wow.  It looks better than ever.

Dude, I spent a whole day trying to figure out that problem!  Now, I think I can make something really good. 

Thanks for getting back to me.  It was very helpful.  I can't wait to show you the GUI.

Unfortunately, I have to do some chores today.  I'm really looking forward to getting this going.

Thanks,

Eric

[Eric Cunningham]

Hi Loren

I've had time to work on the GUI and its looking really good.  Everything will work perfectly.  However, I'm struggling to understand the templates.

I think this is a situation where you could point me in the right direction.

Here's what I'm trying to do:  I'm planning to offer a few alternative templates for the html output. The first is going to be my website template.

So right now, I'm trying to edit the class/method column with the following changes:

1) Remove the "Class/method/Files" links at the top of the column

2) List all classes and methods together in the same column.  The Class tree would be listed first, then there would be a <h2>Methods</h2> headline then the

methods list:

I've hacked solutions by adding a loop after the class_list() method in default/fulldoc/setup.rb but I don't know the "right" way to do it.

I'm trying to make a new template called visualruby that has a fulldoc folder, and holds the minimum number of changes like you suggest.

Please tell me what files I would need to include in my visualruby template folder.  Obviously, I will need a fulldoc/html folder right?  With a setup.rb that overwites the class_list method?

Please give me a clue how to add the methods below the classes and remove the links at the top.

Also, for some reason, it keeps lapsing into the old version of templates with the frames.  I love your new frameless templates, and I've tried to delete every trace of the old yard off my system, but somehow I run yard and the old templates are back.  Does yard hold onto paths to templates?  Can I clear them?

Please let me know.  I particularly need a file list of files I need to edit to make my template changes. Or is just editing the class_list method the way to go?

Thanks,

Eric

  

[Eric Cunningham]

UPDATE:

Ok I've done this:

in my project, I require yard like so:

require Dir.home + '/vrp/yard/lib/yard'

Then immediately:

puts YARD::Templates::Engine.template_paths.to_s

which outputs the proper path:

home/eric/vrp/yard/lib/../templates

This is the proper folder because I downloaded the yard-0.8.7.6.zip file from github and extracted it there.  This is the repo with the tag: v0.8.7.6.  So that should be the latest?

I'm totally stumped as to why its still creating files with the "(frames)" and "(no frames)" links and the big gray bar between the frames.

I distinctly remember an iframes version that looked way better.  Also, the links for methods hilighted when you hover over them like at rubydocs.info.

I really need to be working with the latest version of files because I'm editing the css and templates.  Do you have any clue why I'm getting old templates?

Best,

Eric

[Loren Segal]

The master branch in YARD and the v0.8.7.6 tag are different versions by a lot. Master includes the frameless templates, which have not yet been released under any version. You should checkout the github repository and use master for development (or point your Gemfile at `git://github.com/lsegal/yard` with no tag).

Hopefully that clarifies a bit.

Loren

[Eric Cunningham]

Hi Loren:

Thanks for writing back.  It seems all my issues were git/version related.

I've simply copied the entire "template/default directory, and I'm able to make changes.  However, it feels really "hacky".

I just finished my first alternate layout, so now there is "default" and "visualruby"  I still can't wait to show you, but it still needs a couple of fixes.

Thanks, and have a great 4th of July!

Best,

Eric 

Afer some severe punsih

[Eric Cunningham]

Hi Loren:

So when you try my_yard, please look at this issue that I encountered:  Try generating docs with the "default" template and the "visualruby" theme.  Then when you look at the docs you'll see that the search box and links overlap the headline.  This is due to the fact that the positioning of the search box is "absolute"  Therefore when the size of the text increases, the box doesn't "stack" like a normal div.  The "absolute" positioning of the search box div makes it unmovable.  

Its a small fix, but if we could get it where all the divs are stackable, then users can change the sizes of anything and everything will stack correctly.  This is especially important on mobile devices.

I can fix this in the common.css file, but it would be better to edit the css in the full_list.css.   It would produce a perfectly interchangable set of templates and themes so you can mix-and-match them, and no matter the size of the text, the search box should appear correctly under it.

There are a few compatibility issues that we can address that would really make the project awesome.  Right now, it only changes a few things, but its capable of producing much more artistic layouts.

Hope you're doing great.

Let me know,

Eric

[Eric Cunningham]

Hi Loren:

So the problem that I reported about the class/method/files links and search box not moving when the font sizes change is easy to fix.

All that needs to be done is change the css like so:

#search { position: static; } 

.fixed_header { position: static; height: auto;} 

#full_list { margin-top: 15px; }

In my program, I simply add this code to the common.css file, but a better solution would be to edit the master copy of full_list.css.

These changes have no noticeable effect of how the page renders, it just makes it so when the font sizes change, the elements will stack on top of each other perfectly.

Also, "position: static" is the default, so we'd just need to delete the setting: "position: absolute" and "position: fixed"  This would be an improvement.

The "height:auto" is also the default, so we'd just need to delete "height: 70px" in the .fixed_header class.

There's also a "margin-top: 80px" for the .full_list class that can be eliminated.

All of this should simplify the css.

So these lines:

.fixed_header { position: fixed; background: #fff; width: 100%; padding-bottom: 10px; margin-top: 0; top: 0; z-index: 9999; height: 70px; }

#search { position: absolute; right: 5px; top: 9px; padding-left: 24px; }

#full_list { padding: 0; list-style: none; margin-left: 0; margin-top: 80px; font-size: 1.1em; }

Can read like this:

.fixed_header { background: #fff }

#search { padding-left: 24px; }

#full_list { padding: 0; list-style: none; font-size: 1.1em; }

Really the whole .fixed_header class is unnecessary.

Oops, I just realized the purpose this div is fixed:  It makes the menu visible while you scroll down.

Ok.  I'm going to send you this message so you're aware of the issue I'm facing, but I'll work on it.

This may be a tradeoff:  ability to chage font sizes vs. nice fixed menus.  ????

Best,

Eric

[Loren Segal]

Hey Eric,

There's quite a bit here, so I'll just answer the intent of your proposal:

Turning the #search and header divs into 'static' does actually change rendering behavior on the hamburger menu icon when resized down to mobile mode (outside of yard server). This is fixable, but it sounds like your point is that you want the search box (and menu item friends) on the right to be able to move, which is not intended in the default template. It is marked absolute because it is indeed fixed to that location. Having the links move around based on other layout content would not look that great (you typically want menu items to be in known deterministic locations so users can rely on muscle memory to reach them), so we explicitly locked them in place and had any other text sit under (z-index) so as to not obscure the boxes. This works 95%+ of the time, where typical index content is rarely obscured by the box in any significant way.

Also note that the design is responsive, so if the width of the window is too small to reasonably show the header line, it should swap to "mobile mode" where the menu bar takes the whole top width of the window above the content. Again, this should resize reasonably with typical content.

If you've increased font sizes, you may consider also tweaking the responsive width toggle as well (currently 920px): https://github.com/lsegal/yard/blob/master/templates/default/fulldoc/html/css/style.css#L57-L66

You might also consider moving the search box / other top-right stuff somewhere else permanently if they don't fit your template changes. I don't think we will change the fixed-ness of that div due to the UI concerns above. I'll also point out that the default template is not exactly designed to handle significant UI customization-- and that is not the intent of the template. If you are in fact making significant UI changes, your template customizations should be working around any rendering glitches, or you should consider just replacing the core style.css in your custom template outright and using your own set of style rules from the start. The latter would insulate you from any style changes we make in the future (YARD reserves the right to make significant style changes to the default template across minor versions).

Hope that helps!

Loren

[Eric Cunningham]

Hi Loren:

Everything is working fine with this issue.

I'm really happy with the yard output of the program.  I hope you'll take a look at the project and let me know what you think.

I have a gem posed.  Try:

gem install my_yard

Then cd/your_project

and run my yard:

my_yard

If you just want to see an example of the output, you can look at my website:

http://visualruby.net

It was created entirely with yard and my_yard.  

Let me know what you think.  

Right now there are 2 themes, and 2 templates, but I'd like to add another template or two.

I also hope to start storing the temporary files that are now stored in .yardoc to the home/my_yard folder so users can create docs without adding anything to their project folder.

Hope to hear from you.

Best,

Eric