If I were mean, I’d suggest that it’s the language choice (Ruby versus that other semi precious if misspelled language) but since I’m not, I won’t. As I use templates all of the time I have to wonder about the implementation you are using? Could you expand on the notion of ‘cumbersome’?
Can you elaborate? I’m not sure how the language falls into this?
The YARD template is split into lots of tiny fragments - intended to be able to make modular adjustments. But its structure isn’t all that intuitive and you end up spending a lot of time digging through the source code of that to understand how it’s all connected. Especially when you get issues where the Back button doesn’t work because the template is manually overriding focus etc. In the end I’m starting to feel as though I’m spending more time trying to understand the structure and logic of the default YARD template than it would take to create a new one from scratch that works and looks the way we want it to. We’d then also be free to shape it like we wish it would be instead of brute forcing and off the shelf template.
What templates are you talking about? YARD? Or something else? In the context of documentation frameworks?
The language I was talking about was Perl. And one of the big modules is
the “Template Toolkit” which most who need templates use. There are
assorted other riffs on the theme but that one is the primary. I use it in
a wide range of things from simple generation of JSON files to moderately
complex HTML pages. While I’ve done both in other languages, C and C++ it
is faster and easier in Perl.
Regards ‘cumbersome’, in my estimation you are way over the line dividing
usable and not. I think you would find that it would be time well spent in
writing your own rather than fitting yourself and others to what I refer to
as “someone else’s idea of a good time”. My usual method is to create a web
page without the template portion, dummy in placeholders as needed and then
use that as the basis for your approach. If it proceeds, as usual, the
first few iterations won’t be as flexible as needed, but most likely will
be much better than what you currently have.
Even if you have to do this outside of framework or pre-rolled system,
there is always a way to shoe horn in a web page.
–Hugh
For the Ruby API documentation we need more than just a template - we need a parser to collect the Ruby API information. YARD do this - and we need it for that purpose. So we need to live within its realms. However, up til now we used it’s default template (using Ruby’s ERB template system) with some minor changes. This has the benefit of that we didn’t have to learn how to extract data from YARD’s database after it’d parsed the API source. However, we keep running into scenarios where we want/need to customize - and it’s starting to feel like forcing a square peg into a round hole.
We can leverage YARD for parsing, but just start with a brand new template - not deriving from YARD’s own boiler plate. Already doing this with our API stub generator.
Amending things with your own template still hooked to YARD sounds like a
good investment. From your description, replacing YARD sounds like a
significant task. I think that while you might want to do that at some
point, you are not there yet. It would be an interesting task though…
I really don’t think it’s worth for SketchUp at any point to develop a YARD replacement just for own use. As long as one can stick with official template APIs and avoids customizing internals, one benefits from upstream YARD updates with least investment.
While it’s advertized as “easily customizable”, it is indeed very interesting why still so little alternative YARD templates exist where one could take some inspiration.
Yea, the template is made of many smaller template fragments so it’s “easy” to adjust a part or two. But how the default template actually works isn’t really that obvious. It’s a rather complex system, which I suspect is one of the reasons you don’t see many alternatives.
The anchor-bug is something that really bothers me. And I don’t see an easy fix for that given how the default template is constructed.
Having gotten more understanding of how to access the YARD database I don’t think the effort of creating a brand new template is that great. Certainly not compared to the time spent trying to reverse engineer the existing one in order to make adjustments.
For general readership information:
The SketchUp API documentation is embedded within SketchUp’s C/C++ engine code, and must be parsed out and formatted to display in a web interface.
Since Ruby itself is written in C, Ruby documentation generators can (usually) also parse C code to produce Ruby API documentation. This is a reason why YARD was chosen and also because GitHub has an option to switch on automatic YARD documentation directly from Git repositories.
YARD itself uses Ruby’s simple ERB templating:
-
An Introduction to ERB Templating (Stuart Ellis : Field Notes)
-
ERuby (Wikipedia)
-
Embedding Ruby in HTML (Programming Ruby: Pragmatic Programmer’s Reference)
For an example of a YARD plugin (using SU stubs) see here, Ruby 2.2.7 docs here.
YARD’s template system isn’t that much different from a complex Rails app.
Anything in particular that you’d like to add/change to YARD? I may be able to help, either with code or suggestions as to what needs to be done…
One thing that really bothers me about the default template is that the history doesn’t work for anchors. If you click on anchors to navigate, then try to go Back - then that fails.
See Browser Back is not working · Issue #1071 · lsegal/yard · GitHub and mainFocus() call in app.js prevents jumping to url anchor on page refresh · Issue #1082 · lsegal/yard · GitHub
Another detail I miss from the old site is the custom grouping we had:
I’ve been wanting to add a new tab in the docs to reintroduce these. The tags can be extracted from custom YARD tags added to the documentation.
The last thing is that I wished I had better control over the CSS. I don’t find the default template easy to work with if you want to re-theme to fit our branding. This is another aspect where it feels like the markup also needs to be changed.
If anyone have ideas on to fix the anchor history issue that’d be very welcome. That and suggestions on how to add a custom tab for the custom categories.
1 Like
Custom grouping would be quite nice. I can understand why this grouping disappeared given it’s not defined by class inheritance or anything but it was really helpful when I was new at making plugins. I helped a lot to understand what the different classes was for and to get an overview of what parts there was of the API.
Fixing the anchor history would be great! That has annoyed quite a bit and is quiet distracting. For now I usually use middle mouse button click for the API docs and close the current tab instead of using the back function of the browser.
Is that still live? I kind of recall it. My sites just has what I consider the most popular libraries, I have more that I use locally. Some have essentially the same type of grouping.
I’ve been wanting to add a new tab in the docs to reintroduce these
Another tab, or a replacement for Classes? could be either.
The tags can be extracted from custom YARD tags added to the documentation.
Are they in ruby-api-stubs? I didn’t see any…
If anyone have ideas on to fix the anchor history issue that’d be very welcome.
I almost never use standard YARD (as mentioned, I have a lot local). Can you give my an example? My code is totally different, as it’s using XMLRequest. But, I should be able to fix.
Re CSS, yes, that’s not fun. I tried to separate some of it so a separate file dealt with things like color, borders, etc. Also, a separate file for the LIST and TOC pane. A lot of things overlap…
Not live, no. I scraped a copy of it before it went offline. I can give you a copy of it if you are interested.
I was thinking an extra tab. The alphabetic classes tab is still useful.
No - it’s just an idea I’ve been having - so I haven’t actually added it. I could go about and add them if you like.
Ah, so your version is more like a single page webapp?
That would be helpful. Bintray or something? Others might find it helpful…
Kind of an over used term, but yes, only DOM elements requiring a refresh are downloaded and refreshed on the page, css and js are only loaded on first page load. The main reason I moved to XMLRequest was so the ‘LIST pane’ wasn’t always changing back to the ‘Class List’. Mine stays put, even with a search result.
It’s one of those things many people don’t notice. There’s a lot of things the UI handles differently, and I really didn’t describe them well in the ‘UI Guide’.
Back to the old style list. Rather than go to the trouble of adding tags to every class/module, maybe they could be grouped based on some criteria, For instance, ‘Collection Classes’ seem to be classes with both ‘Entity’ and ‘Enumerable’ in their instance chain.
1 Like
Not true, it varies.
For example:
- Class: Sketchup::Classifications — SketchUp Ruby API Documentation
- Class: Sketchup::Entities — SketchUp Ruby API Documentation
- Class: Sketchup::OptionsManager — SketchUp Ruby API Documentation
- Class: Sketchup::OptionsProvider — SketchUp Ruby API Documentation
… are collections, (with Enumerable mixed in,) but not Entity subclasses.
On the flipside, there are still collection type classes / objects that do not yet have Enumerable mixed in (yet.)
And some in which the API crafters decided to implement their own collection-type methods (each, etc.) rather that mix the entire Enumerable library into the class.
ie:
So, you’ll never be able to rely solely upon the ancestor chain test, be it Enumerable or Entity.
IMO, YARD tags are a simple brute force solution which would only be used by the code that builds the categorical link page once when YARD produces that page.
Another simple brute force solution would be a set of categorical arrays of class names in the Ruby part of the YARD template.
Another issue is there are double-duty classes like Toolbar that are both a UI type and a Collection type.
1 Like
Thanks for the info, Not recalling the original site, I don’t know. As you’ve stated (and I agree with), there are three options for separating the SU classes:
-
Ruby code, based on class/module metadata (ancestors, methods, etc). This will need some kind of exclusion/inclusion collections for the exceptions, as you’ve mentioned. I use metadata with exclusion/inclusion info to generate the std-lib file lists for my doc site. This code would not require adding tags to current code base. If new classes/modules were added in the future, this would require ruby changes only if added items could not be sorted based solely on metadata. But, if this was the case, it would just require adding the item to the required exclusion/inclusion collections.
-
Add custom YARD tags to all current classes/modules. This would still require ruby code to define the categories, or at least their presentation order in the treeview.
-
As you’ve called it, ‘a set of categorical arrays of class names’. This is similar to #1, without using metadata. On principal, this seems rather messy and more unstable than #1 (easy to break or forget).
All three should have some kind of audit code that outputs any classes/modules that were not included in the groupings.
As to ‘when I was new at making plugins’, for me, that was a long time ago. One thought is rather than adding a new list pane, should this kind of info be gathered in a ‘doc’, with more descriptive info? This could have the same lists/groups, maybe in a multi column format, with links for any classes/modules that are listed?
Re the old style vs the new style, I think both are helpful. Using observers as an example, the class list shows the observer class right next to the class that it hooks, while the old style, by grouping observers together, doesn’t connect that.
Anyway, I’ve thought about adding a .yardopts based way to add additional custom lists to my template/plugin (AWS SDK has a custom class list), maybe I’ll have a look at getting that to work, using the original SU ‘custom grouping’ list as the trial code. I should be able to port the code back into standard YARD easily enough…
1 Like
Yes, it does & thanks. It might be a few days…
Any thoughts on what you want to duplicate, eg
Intro?
Quick Reference?
Object Reference?
Release Notes?
TOS?
Mainly the object reference.
I can add a custom @category tag to the various classes.
Maybe wait and see if it can be done with code? As mentioned, code to group by metadata, with arrays for ‘special’ inclusion / exclusion info might be easier and less prone to future breakage…
We’re going to need code for the list regardless…