Docs per Version?

[jimfoltz]

Looking for ideas on the possibility of creating user-selectable versions of the documentation.

Instead of using the @since yard tag to specify which version of SketchUp a method was introduced, it would be better to be able to view the documentation at a specific version of SketchUp. This would be similar to how the Ruby documentation is available for a specific Ruby version.

[thomthom]

One branch per version?

[DanRathbun]

Would it multiply the work in doc'ing to have a branch for each version ? Some API changes occurred during MRs in the old v7 & v8 days. (I already find it a pain to keep specifically switching between the 1.8 and the 2.0 Ruby Doc pages.)

I'd like to see a dropdown version box up in a non-scrolling page header labeled "target version", that would hide old retired methods, and methods that were added later on.

Can the @version tag be used for this ?

[DanRathbun]

Looks more like it will be the @api tag.

see: --api tag to generate documentation for API sets (added in YARD 0.8.1)

[DanRathbun]

It seems that (after reading some posts in the RubyDoc.info "Questions" board,) that in order for RubyDoc.info to maintain separate versioned yardocs, you need to "Release" numbered versions.

This project has had no released "Releases"...

[DanRathbun]

I said:

Would it multiply the work in doc'ing to have a branch for each version ?

Answer is NO. I have been successful in having yardoc generate multiple versions via a cmd script.

Basically it takes a version parameter %1, and uses it in yardoc arguments to:

• use an query switch to filter on @api and @since tags, using the %1 parameter,
• create and use a "./yardoc_db/%1" subdirectory for the database & cache,
• send html output to a "./doc/%1" subdirectory

But there are issues...

All the old @since tags read like "SketchUp 6.0", or "SketchUp 2014", with some of them having a plus symbol on the end. This makes it difficult to use them for comparison. "SketchUp 2014" <= "SketchUp 6.0" ==> true But of course it's not. It is comparing the "2" and "6" character.

Anyway... the @since tags are meant to be visible and convey information to the readers. They will not work so well for showing or hiding information if they are not accurate version numbers. As they are now they are vague release reminders.

[DanRathbun]

Even though I could do a query like: @since.text.split[1].to_i <= %1 .. there is still a disparity between true version numbers and product numbers (which is a marketing invention.)

I find it's best to keep the two tag uses separate.

Use @since for visible product numbers containing a mix of letters and numbers, like Since: SketchUp 2014 (M1).

Use @api for hidden true version numbers, containing only numbers and decimals (or at least beginning with a numeral followed by a decimal,) that can be converted to an integer with to_i. These will be much better to filter on, then the visible "since" information.