My old documentation was hand-coded in HTML. I thought that would be the right way to go at first because, after all, the language was “simple”. Then again, how can anything be simple when it’s over 6000 lines of code? Having become tired of coding documentation, I decided to switch to markup, and with a shiny new logo and a nice docs generator, I now have more professional-looking documentation on Github.
For documentation, I decided to go with Slate. For my own fork, I had to make a number of changes to the underlying libraries in order to correctly render Copper code. That meant delving into the depths of Ruby on Rails, where I found a middleman who told me to look for a french red. A kind fellow taught me how to create a new syntax highlighter for it. Of course, he didn’t mention the other requirements, so I was off and sailing without a map.
For this little adventure, I had to set up RVM (Ruby Version Manager). It’s a nice tool that lets you run different versions of Ruby on the same computer without them interfering. I followed the instructions on its Github page somewhat, but I decided I didn’t want to logout and login and have my terminal always boot up in login mode, so I stick with using bash –login. It was alittle tricky setting up RVM without login. Since you can’t use sudo, you have to login as root and perform installation from there.
Once RVM was setup, I had to download and install middleman and rouge. However, you might notice that the version of Rouge used by Slate is old. That’s ok. Bundler gets it and preserves it for you, but you might wonder like I did how to change it. It’s simple: Since Ruby isn’t a compiled language, all you have to do is find the rouge-2.7 (?) directory in your RVM gems folder (which, for me, was hidden in $HOME/.rvm/) and add your language lexer into the lib/rouge/lexers directory.
While I was at it, I added a couple of themes to rouge. You can find these in my fork of rouge. If you want to add your own themes, you’ll need to modify the lib/rouge.rb file. Look at the stuff at the bottom and you’ll see it’s readily apparent how themes are added, so I won’t elaborate here.
My new theme for the Copper documentation is “candy_apple.rb” – an autumn-themed color set. I liked it so much that I decided to make a similarly-colored syntax highlighter for gtksourceview and a new Copper highlighter to work with it. The latter has been added to the Copper IDE folder. The former I was hoping to add to some public database so more people could find it, but I haven’t found one accepting submissions. Oh well. Maybe I’ll include it with Copper anyways if not in another repository.
Overall, everything looks much better in my opinion. That’s not to say it’s perfect, of course. The Slate docs can be alittle crowded, I’ll admit, but I like it more than MkDocs, which unfortunately seemed to be the easiest alternative.
That said, the docs are ready. 🙂 Feel free to comment if you see anything missing that should be added.