Week 4: week 4 progress update.
Tags: rdoc, ruby, gem, rails
Published: 2022-10-17 09:20:22

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](https://kapeli.com/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](https://skatkov.gumroad.com/l/pxbxx). 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](https://github.com/freeCodeCamp/devdocs) documentation.  Ran into issues converting html to markdown on a fly and couldn't proceed with implementation.

[I did research about alternatives](https://www.poshtui.com/quest-to-generate-documentation-in-markdown/) 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](https://github.github.com/gfm/) 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 <path>/rdoc-markdown/rdoc-markdown-<version>.gem_

Gem is already open-sourced at [github/skatkov/rdoc-markdown](https://github.com/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](https://github.com/skatkov/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.