Markdown in doc comments

[bookmoons]

JSDoc can interpret doc comments as Markdown. I'm using this for formatting and cleaner links. But I guess it outputs HTML, so when used with sphinx-js you end up with HTML tags in your docs.

class MissingValueError()
    <p>Required value missing error.</p> <p>Thrown when an operation requires a value that is not available.</p>

    MissingValueError.name
        <p>Error type name.</p>

Is there any way to use Markdown with sphinx-js?

[erikrose]

Are you talking about the optional http://usejsdoc.org/plugins-markdown.html? At present, you can use reStructuredText in your JS code, which matches well with Sphinx's default of the same. I haven't given any thought to Markdown support, but I'd entertain a patch. It might be as simple as telling sphinx-js to not HTML-escape input.

[bookmoons]

Yes that's the one, the markdown plugin.

Thanks. Going to look into it.

[bookmoons]

The code is clean. Such a relief when it's easy to get your head around something.

Proposed an enhancement to @see tag support #70, in preparation for this.

[erikrose]

Glad you like it! I'll put your @see addition in my review queue.

[bookmoons]

Working example of where I'm heading here.

The comment looks like this:

/**
 * [Bitcore][1] based implementation of message encryption.
 *
 * Uses:
 *
 * - [crypto][2] for hashing.
 * - [bitcore-lib-cash][3] for key operations.
 * - [@bookmoons/bitcore-ecies-cash][4] for encryption operations.
 *
 * Network values are bitcore-lib-cash `Network` instances. Standard networks
 * are available through `bitcore.Networks`.
 *
 * [1]: https://bitcore.io/
 * [2]: https://nodejs.org/dist/latest/docs/api/crypto.html
 * [3]: https://www.npmjs.com/package/bitcore-lib-cash
 * [4]: https://www.npmjs.com/package/@bookmoons/bitcore-ecies-cash
 *
 * @module cashshuffle/crypto/bitcore
 */

That produces this page: https://bookmoons.github.io/cashshufflejs/module/crypto/bitcore.html

[erikrose]

On second thought, declining to escape HTML in doclets would prevent Sphinx from rendering to anything but HTML. It makes me suspect that the architecture of Sphinx won't permit that approach; I wouldn't be at all surprised if Sphinx assumes a big reST-expressible AST as a prereq to rendering anything.