Generating Markdown docs

[mefernandez]

Hi Romain,

I find this API documentation approach quite interesting. How about an option for generating Markdown besides/instead of HTML?

It would be nice to generate a quick README.md to read the generated API doc directly on GitHub. What do you think? Would it be easy to implement?

[rprieto]

Hi Mariano,

It's definitely possible, the generation is done in 2 steps:

1. instrument supertest and collect request/response information
2. render the in-memory model to HTML pages

I could probably split step 2 to have a choice between HTML & markdown. However it could become a pretty long Markdown file, especially with all requests/responses bodies expanded. Let me know if you have ideas what it could look like.

Otherwise you might also be interested in the --reporter markdown option of Mocha. It would get you close, but unfortunately it just prints all the JavaScript code in every it(), no pretty transform there.

[mefernandez]

Hi Romain,

It would be awesome if we could generate something like GitHub's API docs.
http://developer.github.com/v3/

Of course, I realize the limitations on doing such a thing with just collecting information from supertest and outputting Markdown. But trying to go that direction feels quite alright.

I'll fork your repo and come back with what I've found if you're interested.

Cheers,

Mariano.

[rprieto]

That's actually really close to the current output, so it should be easy! 3 things that come to mind browsing their docs:

1. Look and feel

The GitHub docs seem to be a normal website, so if that's the main concern you should be able to make it look like that easily. supersamples supports custom CSS in the opts file.

2. Markdown support

Regardless of look-and-feel though, actual Markdown output would definitely be nice. I just thought for example, you could also push the generated docs to the wiki repo of any project to get browsable docs that support multiple pages.

3. Content

Their content is also very close: URLs, custom headers, response payloads, a few error cases... The only extra thing is that they sometimes explain request parameters or fields in the responses. That's definitely handy, but I really want to keep the fact that supersamples doesn't use any hardcoded or text-only description of parameters or error codes. I've been down that path and they become out of date so fast... which was the reason for creating this :) I believe in most cases these can be explained by a few more specific tests, with smart mocks that only show what we care about.

Anyway it looks like 80% of Github's documentation could be covered without, for example feeds events or comments.

So I'm not sure which of 1, 2 or 3 you care most about, but I'm happy for you to spike something if you're still keen. I'll be happy to help as well so let me know what you have in mind.

[mefernandez]

That's great. I will take it step by step and see where this goes.
I originally became interested in this because I wanted to avoid pushing/building documentation. I mean, as you suggest, you can push docs to GitHub's wiki, or even create a GitHub page with the HTML supersamples already generates. But I like the idea of a simple README.md automatically updated to just read it on GitHub.
So first things first. I'll take a look at the code and see what happens.

[mefernandez]

Hi Romain,

I've pushed a first attempt of a Markdown reporter to my fork. Take a look at what's being generated at https://github.com/mefernandez/supersamples/blob/master/test/markdown-result.md

It looks quite nice. It keeps the tests' hierarchy as titles, and wraps request and response in code blocks. I wanted to make responses look alike GitHub's API design, with a split box for HTTP headers/body but there seems not to be a way to do that with just plain simple MD.

The code is not in a final state, since I took some shortcuts. I'm writing directly to console and I've hardwired the markdown reporter by commenting out the HTML one. I'll read supersamples.opts file to choose which reporter to use in the next commit.

You can run my fork with this line: mocha --compilers coffee:coffee-script --reporter supersamples example/test/ > test/markdown-result.md

So, what do you think?

Cheers,

Mariano.

[rprieto]

Hey Mariano,

Sorry for the (very) slow reply. The Markdown output looks great!

I have a branch in progress to support multiple "rendering engines". If you're still interested I can ping you later this week when it's merged, and you should be able to put all your code into:

supersamples/lib/renderers/markdown/index.js

exports.render = function(model, options) {
   // model is an array of all samples and their metadata
   // options is whatever the user specified for that renderer in `supersamples.opts`
};

[mefernandez]

Hi Romain,

Sorry for this equally slow response. I've been up to so many things...
Anyway, that sounds terrific. I'll try to make some time to merge it and give you feedback.

[rprieto]

No problem, let me know how it goes!

[kfatehi]

this is really great. awesome work on this -- thank you. looking forward to the markdown support. currently in my CICD i generate supersamples (and slip in the README.md as an 'intro' doc) and push that to my project's gh-pages. Being able to do similarly with the wiki in markdown format will be fantastic too

[freefri]

I guess there is no progress on this anymore. Is there any branch where we can test this feature?

[rprieto]

Sorry you're right the work hasn't been fully ported.
There is now support for multiple rendering engines, so we just need to include @mefernandez's great work into lib/renderers/markdown/index.js.