So it states that “the recommended way of using it is through Docker” which is immediately a red flag. Why would I want something complicated like this if I can just run rdoc lib (shipped with Ruby’s standard library) and have proper documentation?
There would need to be substantial benefits if we need to jump through hoops like this.
That’s a great point!
As our intention was to output an static website, Next.js just made sense, since we could use new technologies and still be able to generate HTML and JS allow it to be hosted without worrying too much about static assets.
Personally, I’d rather just run a container instead of installing Node on my machines, therefore the recommendation. But you are able to just clone and use it if you wish to.
By the way, if you have any thoughts on how we could do better on this part, I’d love to know! Specially if we can ditch Node altogether and just use plain Ruby. <3
You might take inspiration from the latest Rails development which tries to avoid external dependencies as much as possible. And the Bridgetown guys/gals are also in the process of removing (or have already removed) the dependency on Node.js.
What I would like from a new documentation generator like docrb is integration into static website generator tools so that the API documentation can be an integrated part of the website, not just an add-on to it. I have done something like this with webgen and RDoc, see https://hexapdf.gettalong.org/documentation/reference/api/HexaPDF/Content/Canvas.html#method-i-translate as example where the API documentation is built when the website is built. And the API documentation is also enhanced with automatically generated images.
I haven’t really written any Ruby outside of chef/vagrant contexts, but I did spend part of the weekend prototyping something in Ruby because I wanted to try out a markup language implemented in it.
While looking for documentation on a pair of CSS modules I ended up landing at rubydoc.info (not sure if this is a ~canonical Ruby gem doc source) and found that I had a hard time focusing on information. I didn’t really take the time to break down why, but I ended up finding it more efficient to just read the source.
Congrats on pulling this together. I’m not certain how I’d feel using it, but I do think it looks both more useful and attractive than what I was getting through rubydoc.
Anyone else wanting to follow along, here are some comparisons using the same logrb gem:
doesn’t look like the component pages have an easy way to get the permalink for each entity or get back to the Readme tab
I like the ~member-visibility checkboxes in the component view (and the fact that they’re hidden, though “Show More” didn’t quite communicate what I found there–I was expecting more information or meta-data about the class.)
Mid-scroll, it isn’t really obvious which entities the show-source links are for. They don’t link out, so hovering the link doesn’t help clarify. It also isn’t obvious that they’ll show it inline. I think this could maybe just be left-aligned with a clearer affordance?
I would only use rubydoc.info as last resort if the project doesn’t offer its API documentation itself. Alas, most projects just defer their API documentation to sites like this without making efforts to provide good documentation themselves.
So it states that “the recommended way of using it is through Docker” which is immediately a red flag. Why would I want something complicated like this if I can just run
rdoc lib(shipped with Ruby’s standard library) and have proper documentation?There would need to be substantial benefits if we need to jump through hoops like this.
That’s a great point! As our intention was to output an static website, Next.js just made sense, since we could use new technologies and still be able to generate HTML and JS allow it to be hosted without worrying too much about static assets.
Personally, I’d rather just run a container instead of installing Node on my machines, therefore the recommendation. But you are able to just clone and use it if you wish to.
By the way, if you have any thoughts on how we could do better on this part, I’d love to know! Specially if we can ditch Node altogether and just use plain Ruby. <3
You might take inspiration from the latest Rails development which tries to avoid external dependencies as much as possible. And the Bridgetown guys/gals are also in the process of removing (or have already removed) the dependency on Node.js.
What I would like from a new documentation generator like docrb is integration into static website generator tools so that the API documentation can be an integrated part of the website, not just an add-on to it. I have done something like this with webgen and RDoc, see https://hexapdf.gettalong.org/documentation/reference/api/HexaPDF/Content/Canvas.html#method-i-translate as example where the API documentation is built when the website is built. And the API documentation is also enhanced with automatically generated images.
I haven’t really written any Ruby outside of chef/vagrant contexts, but I did spend part of the weekend prototyping something in Ruby because I wanted to try out a markup language implemented in it.
While looking for documentation on a pair of CSS modules I ended up landing at rubydoc.info (not sure if this is a ~canonical Ruby gem doc source) and found that I had a hard time focusing on information. I didn’t really take the time to break down why, but I ended up finding it more efficient to just read the source.
Congrats on pulling this together. I’m not certain how I’d feel using it, but I do think it looks both more useful and attractive than what I was getting through rubydoc.
Anyone else wanting to follow along, here are some comparisons using the same logrb gem:
Some small thoughts:
I would only use
rubydoc.infoas last resort if the project doesn’t offer its API documentation itself. Alas, most projects just defer their API documentation to sites like this without making efforts to provide good documentation themselves.