This is a second progress report for a command line tool called "Posh TUI". It's an API documentation browser for ruby developers.
My name is Stanislav Katkov. I got really frustrated that there are no viable alternatives for Dash, so embarked on a journey to build one. If you are not using Mac/OSX or prefer command line tools to GUI tools and share a similar frustration—you might want to buy a lifetime license. This will guarantee that you'll get any updates of app for free in future and your feedback will be driving roadmap for this tool going forward.
This deal is limited to 20 licenses.
Background
This project is basically split into two major components:
- CLI/TUI app to review documentation
- framework to generate and host required documentation
Initially, attempted skipping documentation part and tried to build CLI/TUI app based on devdocs documentation. Ran into issues converting html to markdown on a fly and couldn't proceed with implementation.
I did research about alternatives and decided to proceed with RDoc integration instead.
Progress report
In these two weeks, I had to move my entire family from Thailand back home to the Netherlands. After two months of absence from home, we had a huge layer of dust waiting for us to clean. Most of my spare time in weekends was spent cleaning everything up.
But there is still some progress to report.
Rdoc-markdown gem
Started out, by just forking rdoc repo—effectively creating a fork with markdown generator. But that's a bad idea, easier to write a plugin!
There area only couple of things to remember while writing rdoc plugin. Rdoc will look for rdoc/discover.rb files in installed gems, this file is used to load entire plugin.
Testing a rdoc plugin is way trickier, though. How would you even test it locally? Having a robust testsuit is close to impossible to cover all possible scenarios. Which flavor of Markdown to support?
I have settled with Github Flavored Markdown as a standard. But even with this well-defined standard, it's close to impossible to validate programmatically.
Entire testing is being done manually:
- Build and install new versions of a gem regularly
- Store source code of ruby and Ruby on Rails project
- Generate documentation with --markup=markdown --debug
- Compare with HTML version
All of it is a manual tedious process, time-consuming, and fragile. I probably typed these commands a couple of hundred times at this point.
- gem build rdoc-markdown.gemspec
- gem uninstall rdoc-markdown
- gem install /rdoc-markdown/rdoc-markdown-.gem
Gem is already open-sourced at github/skatkov/rdoc-markdown. It currently generates readable documentation in Markdown, but there are still some quirks in rendering I stumble upon.
What's next
Wrapping up rdoc-markdown:
- Address all the rendering quirks that I'll find during testing
- Produce a SQLite database with index of entire content
- Post to various ruby related communities to get initial feedback.
- Produce documentation for supported versions of Ruby and Ruby on Rails gems.
After move on to building a CLI app again (looking forward to coding some GO!). My initial goal is to integrate licenses from gumroad and to be able to analyze Gemfile (so I can derive ruby version and rails version from it).
That's all for today, folks.
Top comments (0)