Some how I really want to figure out a system where user-improvements to the API docs can be near-automated.
In short, the API is large and so updates are slow. The documentation is not in a form where community contributions can be accepted. Having the documentation in a form which would allow community members to make contributions might speed things up by spreading the work out which would benefit the entire community.
Does anyone have any ideas on how an a system could be setup to allow contributions?
If the docs are already on GitHub, why can’t the usual process of pull (or do I mean push?) requesting be used, with Trimble controlling which requests are accepted?
The Respository only contains HTML files which are generated by the yard utililty from the SketchUp source code. It doesn’t make any sense to edit them. Any changes will be over-written the next time the docs are generated.
A step in the right direction is the stubs repo which contains stub files also generated from the SketchUp source code. yard can be run directly on the files in this repo and should generate API docs identical to the online version. Edits to the stubs repo can more easily be merged back into the source code.
Thanks for the links. I was going to suggest the only the comments need be output, but the stubs also aid IDE’s to do auto completion and method suggestions.
The documentation is currently extracted from our C++ source files. From that we use Yard to generate the documentation We use for most part the default Yard template, but with some minor customisation.
Yard provides us with an easier documentation process than our old documentation. The previous system was a custom system which was hard to maintain and it wasn’t even easy to tell what syntax it accepted.
Our Yard setup uses RDoc with the addition of Yard tags - which provides a more formal presentation of argument types, return types etc.
The generated documentation is uploaded to GitHub using their GitHub Pages features.
An extra bonus of using Yard is that it generates a database of what i parses, and provides an API we can use to create additional tools. By utilising that we were able to generate Ruby stubs of the API that can be used by IDEs for insight to our API - auto-complete etc.
Now, while the process of updating the documentation has been immensely improved the logistics of updating all the 1300+ methods is very time consuming. At the moment we work in an incremental way, fixing things as we go along. We also try to set aside some time to to just fixes to the docs.
Personally I wish the docs could accept user contributions. The main challenge here is that the docs are located along with our source code which we cannot publish.
One thing that could be tried right now is accept pull requests on the Ruby API Stubs and then we’d simply manually backport it on our end.
But, I prefer to automate as much as possible - toying with the idea of some kind of script that could take the diff, or patch, for a Pull Request and use that to figure out what method/class/module the doc comment relate to, and then map it back to our original source code. Something that bring the process down to a few clicks - making the main job of updating to be mainly reviewing the changes. At the same time I fear that might be over-engineering it.
I had a quick look at some scripting tools. I was able to very easily get YARD to look up an API object (module/class/method/constant etc) and return the source file and line number range.
So if I can just work out a tool that takes a git diff and parse out which API documentation comments were changed then a full round trip is very close! I’ll have another look tomorrow. Might even get a prototype running.
Just in case someone were thinking of doing some fixes; I’d recommend you hold off until later in January. I want to make some changes to the stubs repo first. Change the file structure to match that the API docs use. Fix the missing module/class descriptions. And verify that the round-trip script is working reliably.
I think there should be a fork of basic stubs for IDEs, as attempting to use one repository to support both IDEs and the API documentation could limit one or the other.
I am more wary of the need for IDE support limiting what needs to be done for proper (or more improved) API documentation.
So I’d suggest a fork of the stubs now just for IDEs. (Or keep a backup somewhere.)
While you are looking at how the documentation can be improved, could you also please look at why it isn’t usable on a mobile or tablet? Pages aren’t fully visible, even on a very high-res screen, but scrolling either sideways or up/down doesn’t work. Nor does zooming.
It makes the docs effectively unusable on portable devices.
Doesn’t work too well in a desktop browser either - goes funny when you narrow the page in a not very helpful way - first the Class- Methods- or Files-list disappears, then the text of the right hand detail column.
It has indeed changed since I last looked on my phone, but is just as described on desktop in Chrome (on Mac).
On phone (Galaxy 7 Edge), I can now pinch and zoom on the opening page, and scroll up/down/sideways. But there is no Class, Method or Files column, just one alphabetical list, under a page heading of File Listing. It seems on a quick glance to show SU, Geom and UI Classes, and a small handful of other second level sub-Classes.
The three line menu does nothing, either on the opening page or a small sample of linked pages.
So I think I’m still missing something on mobile platform.
Have you thought about a separate bug tracking system (or simple text file, or separate forum topic) that developers would describe issues (that may or may not be valid)? Or will the Github “GitHub - SketchUp/ruby-api-docs: SketchUp Ruby API Documentation” meet that need? Any documented issue would need to have enough detail that included the proposed text change. Some sort of vetting is needed, with a Sketchup team member examining replies to issues and becoming the “benevolent dictator” (I vote that @tt_su guy) .
I can think of three types of API doc issues:
The code works as desired, but the API docs differ from actual behavior;
The code doesn’t match the API docs and it is considered to be a coding bug. It is unlikely to be fixed for the next few years, and the docs should be changed to match the code;
The doc’s coding example is too simple and needs expanding.
It does. All GitHub repositories have issue tracker dBs, and all sorts of other nifty tools.
If you had hovered over the issue link I posted above, you’d have seen that the URL goes direct to a specific issue in the issues dB.
So removing the specific issue number (from the end of the URL) gives you a link to the issue listing:
… to which I’ve added 8 issues in the past week.
GitHub has nifty type marker “labels” that can be created by contributing members and attached to any issue. If you look above in the issue link, you’ll see ThomThom already attached 2 to that issue. (ie, “question” and “enhancement”.)
This is the list of the labels ThomThom (& etc.,) have already created:
Normally this is a documentation error. But we need to be careful as sometimes the API code has changed over the years (perhaps due to the change in embedded Ruby version.)
But, yes, this is the kind of error we are logging, in the GitHub issue tracker for the ruby doc project.
No, this is not a documentation error, this is a API code (engine) error / bug.
This goes into another internal tracker dB, which is not public.
BUT, the docs do have bug note boxes in them, that attempt to notify the coders of bugs and pitfalls. (It is okay to file an issue to add such notes to the API docs.)
There is a separate GitHub project for expanded examples and tutorials:
… which has it’s own issue / feature request list:
That said, I don’t see a reason why (in the future) the example project could not get a YARD template that outputs “Example” pages that can have links from the Doc pages. (Either the “Files” listing, or a dedicated chapter.)
