Adding GitHub Flavored Markdown support as doc format

[sporniket]

https://github.github.com/gfm/

It would be nice for me, as all my docstrings are written using that format, and given that this is my go-to format when writing structured text in general.

I did consider using rest or epytext, but I admit that fenced code blocks, atx headers and * bullet lists are too much addictive for me.

[tristanlatr]

Hello @sporniket, thanks for opening this feature request. In order to add a new docformat, we need to implement/make us of a docutils parser for the given docformat. I know MyST is a markdown parser for docutils, but I’m not sure it support the GitHub flavor of markdown.

Would you be available to implement that feature? Thanks

[sporniket]

Thanks for your reply.

I am not available for now and the coming semester will be busy for me. If by chance I would happen to write such a parser during next year, what would be the preferred interface to provide ?

E.g. parsing a whole chunk and get a tree/list/whatever like parseTree = myGtmParser.parse(fulltext), or an iterator that serves each token/chunk one by one e.g. something like for i,chunk in MyGtmParser(fulltext): #process each chunk ? or another form ?

Regards.

[tristanlatr]

Thanks for your interest,

This is the interface pydoctor uses: https://pydoctor.readthedocs.io/en/latest/api/pydoctor.epydoc.markup.restructuredtext.html#parse_docstring

But basically it boils down to a full text parsing of the docstring that creates a docutils document instance, as well as for fields. With the ability to report non-fatal errors in a list passed in parameter.

Regards

[tristanlatr]

The principal chalenges I foresee with adding markdown docstrings support to pydoctor are the following:

• How should google and numpy styles be integrated ? They are currently implemented with the napoleon pre processor that transforms the docstrigs to reStructuredText, which is incompatible with markdown by nature. We could use docstring parser, but it would duplicate the google/numpy implementations, eventually we could replace napoleon with docstring_parser. But this means we need to implement some kind of docutils bridge, in any case we need a docutils parser or adapter of some sort.
• How should we write cross references ? Let that be an internal reference or an intersphinx reference. There is no standard for such links, mkdocstring is using [target][], pdoc is using `target`, looks like mkapi supports both, but MyST uses something different that is closer to the default markdown syntax.

[sporniket]

Thanks for the pointers and the insights.