AsciiDoc vs Markdown

I’ve been a markdown user almost exclusively - more due to github and stackoverflow popularizing the format. Markdown is great for lightweight markup and with excellent tools like Pandoc, it’s a joy to produce good looking technical docs. Suffice to say that I’ve been taken with markdown and even use it to produce word documents and such.

While Markdown is great, it has it’s share of niggles - try to go beyond the basics and want some advanced features and you get into trouble. Want tables? Or want to include diagrams generated from ascii art? It’s all a hit or miss depending on which Markdown implementation you’re using. Ditto for things like nested lists and lists with sub paras and whole lot of other niggles where each different Markdown implementation may end up behaving differently. There have been some efforts to have a rigourous spec but I don’t think things went anywhere with CommonMark - atleast, I don’t see it used much anywhere.

For the latter problem of wanting to include diagrams, I wrote mermaid-filter and while it’s super useful, it works only with mermaid. If you want to use graphviz or something like that, sorry - you’re out of luck.

I’ve resigned myself to Pandoc’s version of markdown - since I end up using pandoc almost always to convert to other formats.

Wanting a better lightweight markup format, I spent sometime looking at alternatives this weekend and came upon asciidoc - and I’m just wowed! It pretty much ticks all the boxes in terms of all the niggles I have with Markdown and it’s not so different from markdown either so that transitioning to AsciiDoc is a non issue.

AsciiDoc has the following over Markdown:

1. Supports advanced formatting natively.
   
   1. Native code formatting with pluggable syntax highlighters.
      
   2. code call outs - oh so useful.
      
   3. Cross references
      
   4. Tables
      
2. Rigourous spec
   
3. Smart, natively extensible
   
   1. For ex: want diagrams? A whole bunch are supported
      

It’s miles ahead of Markdown, IMO - so much so that I’m jumping ship :)

So, in a rush of enthusiasm, I’ve updated EasyBlogger with asciidoc support and pushed a release out to PyPI. This also means that I would probably not need mermaid-filter anymore - but hey, you should see better looking posts from me here.

Blogger REST Api inconsistencies

Yesterday I noticed that blogger API now supports posting as draft. This wasn't the case when I wrote easyblogger - a cli tool to edit and post to Blogger from Vim.

In any case, since the API now has the ability, I updated EasyBlogger to post as draft. Trouble came when I went to update an existing draft - it fails with a 404

C:\Users\raghuramanr>easyblogger file c:\Users\raghuramanr\blogentries\a.sample.draft.md
....
....
    raise HttpError(resp, content, uri=self.uri)
googleapiclient.errors.HttpError: <HttpError 404 when requesting https://www.googleapis.com/blogger/v3/blogs/7642453/posts/1132458907272271320?alt=json&revert=false returned "Not Found">

Trying to get a post saved as draft fails - apparently, one needs to pass in view="AUTHOR" to get drafts. fair enough..

But my first reaction? Sheer happiness! There's hope!!! If Google can screw up REST API consistency and principle of least surprise, there's hope for us mere mortals who write APIs at work in enterprisey situations that're probably going to be consumed by one or more internal teams at most.

Anyway, here's how I've patched it together but publishing it first, then editing it and then reverting it to a draft if needed. Yuck!

       postStatus = service.posts().get(
            blogId=self.blogId,
            postId=postId,
            view="AUTHOR",
            fields="status"
        ).execute()['status']
        mustRevert = postStatus != 'DRAFT' and isDraft
        mustPublish = postStatus == 'DRAFT' and not isDraft
        if postStatus == "DRAFT":
            service.posts().publish(
                blogId=self.blogId,
                postId=postId
            ).execute()
        resp = service.posts().patch(
            blogId=self.blogId,
            postId=postId,
            body=blogPost,
            revert=mustRevert,
            publish=mustPublish).execute()
        return resp

What publishing a python module taught me

Programming in Python

So I've mostly used python for one off scripts and tools and at one point for a serious foray into Django - but never came into a situation where I'd thought of publishing anything.

Hmm - crossed that bridge over this weekend - and its been a fun journey. I'm writing this post with what I wrote :)

Things I've picked up

Code

1. Better understanding into Python modules, classes and code organization for libraries.
   • Be Pythonic: init.py
2. Good unit tests
3. Mocking in python
   • Python Mocks
   • Mocking patterns: chained calls, partial mocking and open as context manager

Packaging

1. Packaging with setup.py
   • What I used to get started
   • Reference
2. pip, setuptools, easy_install and their idiosyncracies
3. Install a platform specific script
   • reference
4. PyPI - registering and publishing
   • Tutorial One point to note - if you create the .pypirc manually, you will need to manually do a python setup.py register. If you skip that, python setup.py sdist upload will fail with a 403.

Testing

1. virtualenv - this link
2. Testing platform specific scripts installed with tools above
3. Coverage

Coding/Style/Syntax linting

1. pyflakes, pylame, pep8 and integration in Vim with Syntastic

What I really, really liked

1. That I didn't miss a debugger
2. That tests were short and sweet
3. good code coverage out of the box
4. pip
5. Overall, how pleasant it was and how much I enjoyed it.

Where I had hiccups

1. Mocks in python were a little hard to debug/understand
2. Should have written the tests first - but it came as an afterthought after I decided to publish.
3. Finding good documentation on packaging - for ex:, its hard to find a good walkthrough of how to publish

Just putting finishing touches and a little polish for a v0.9 release. Basically this post itself is nothing but a test. Should be out with it in a day or two.