I want support for rst, as well as markdown, in extraDocs

[mirisuzanne]

No description provided.

[jgerigmeyer]

@mirisuzanne How are you imagining this should work? Right now we just take an array of file paths, or objects with name and path keys. Do we auto-detect based on .md or .rst? What's the fallback if those aren't provided? Can the user specify for each file individually?

As a starting place, I could imagine something like:

extraDocs: [
  { name: 'Configuration', path: './CONFIGURATION.md' }, // parsed as .md
  './CHANGELOG', // parsed as .md
  './CONTRIBUTING.rst', // parsed as .rst
  { name: 'Another', path: './ANOTHER.md', format: 'rst' }, // parsed as .rst
],

That is, we decide based on the following, in order:

1. format option ('md', 'rst', or 'none')
2. filename extension (.md or .rst)
3. .md (default)

Or maybe we should default to none, if no file extension or format is provided?

[mirisuzanne]

@jgerigmeyer I like your suggested approach.

[jgerigmeyer]

@mirisuzanne Do you think we should automatically parse as markdown (which is what we're doing now), or only if the user specifies format: 'md' or the file has .md?

The former (doing it automatically) fits with SassDoc -- and shouldn't usually cause problems -- but the latter is a clearer API, I think.

[mirisuzanne]

I think either is fine. I don't mind having an implied default. That's pretty standard for an API.

[jgerigmeyer]

There currently isn't a good rST parser for node.js. https://github.com/frantic1048/Est is the best I've found, but it still doesn't handle links or images very well. I'm not sure it's worth putting more time into this.