Add pandoc to travis-ci.

[daspecster]

I want to make sure this installs on travis without issue.

[dhermes]

@daspecster I also didn't get a notification about this PR. I wonder what's up with GitHub?

[dhermes]

Also, we intentionally use sudo: false to get the new infra. on Travis.

This PR doesn't explain why pandoc is needed.

[daspecster]

Hmm, I didn't assign anyone to it. I just wanted to play with some stuff. That might be why you didn't get notified?

So I'm thinking of using pandoc to parse some of the RST *-api.rst and *-usage.rst files to then be inserted into the JSON tree somewhere.

[theacodes]

why not just use the restructuredtext library?

[dhermes]

Big time 👎 on using pandoc. Agree with @jonparrott

[daspecster]

@jonparrott, docutils? I parsed it with that using the rst2html.py script, but when there's an error (like an unknown directive found), it injects the error into the html.

Pandoc seems to clean those up and handle the some of the navigation issues fairly well.

docutils Example:

I'm all ears(eyes in this case) on suggestions. I would really like to try and not write more bug prone parsing code to handle these things.

[dhermes]

The pan in pandoc is the problem. We don't need a jackhammer, just like a tiny magnifying glass or something.

[theacodes]

@daspecster the rst parser in docutils is really quite flexible, but perhaps you'd be better off starting with a sphinx extension to do what you need?

[daspecster]

@dhermes that is true. I'm sure there's more stuff out there.

@jonparrott, I spent about a week with sphinx, sphinx extensions, docutils and the way that the node tree is built, I couldn't find a way to extract the correct parts of the docstrings.

It would add the nav and references since those are sphinx directives anyway. Those links don't work in the JSON site.

It seems redundant to parse them with sphinx and then parse them again to clean it up.
You can kind of see what's happening under the hood by using the json or xml builders.