search

miyuchina / mistletoe

A fast, extensible and spec-compliant Markdown parser in pure Python.
MIT License
841 stars 119 forks source link

Renderer for Natural Docs #191

Open eminakgun opened 1 year ago

eminakgun commented 1 year ago

I need a renderer for natural docs and planning to implement one. ND is primarily targeted for source code documentation but you can include any text in any file extension supporting its parser. Any suggestions? I am planning to derive from BaseRenderer

pbodnar commented 1 year ago

@eminakgun, I checked https://en.wikipedia.org/wiki/Natural_Docs and I'm not quite sure how mistletoe can help here.

If I get it right, ND parses source codes in a selected programming language and generates an HTML documentation from it. I.e. something similar to Java's javadoc tool. So is your idea to firstly generate markdown from ND and then use mistletoe to convert it to the final HTML form? If so, wouldn't be mistletoe's HTLMRenderer be enough? Or maybe your idea is about something quite different?

eminakgun commented 1 year ago

Not exactly, planning to have the documentation in markdown except code(since ND already does the job for code). And because HTML output of ND is required, wanna produce ND format from markdown using mistletoe. ND does not only parses the source code, it can scan any file using that uses its syntax. Syntax includes code snippets, titles, lists, images etc. just like markdown does.

I will include an example to be more clear.

pbodnar commented 1 year ago

Thanks for the explanation. 👍 I think the functionality of ND you mention is described within "Text Files" on https://www.naturaldocs.org/getting_started/documenting_your_code/#extra_documentation, right?

So is the motivation for this "Markdown to ND renderer" driven by the fact that the ones who will write these extra documentation files don't even need to know the ND syntax?

Anyway, it looks like you can start by creating a new class called NaturalDocsRenderer, derived from BaseRenderer, with render methods implemented in a way that they return strings / lines in the ND syntax for every given token type. If needed, you can also introduce custom tokens. There is a small piece of documentation for this: https://github.com/miyuchina/mistletoe/blob/master/dev-guide.md#creating-a-custom-renderer. I guess one of the challenges might be handling the indention (at the root level, at minimum) as required by the ND syntax. I've seen it for just a minute by now, so apparently, I cannot give much advice here... ;)

eminakgun commented 1 year ago

Thanks for the explanation. 👍 I think the functionality of ND you mention is described within "Text Files" on https://www.naturaldocs.org/getting_started/documenting_your_code/#extra_documentation, right?

Yes.

So is the motivation for this "Markdown to ND renderer" driven by the fact that the ones who will write these extra documentation files don't even need to know the ND syntax?

Exactly.

Anyway, it looks like you can start by creating a new class called NaturalDocsRenderer, derived from BaseRenderer, with render methods implemented in a way that they return strings / lines in the ND syntax for every given token type. If needed, you can also introduce custom tokens. There is a small piece of documentation for this: https://github.com/miyuchina/mistletoe/blob/master/dev-guide.md#creating-a-custom-renderer. I guess one of the challenges might be handling the indention (at the root level, at minimum) as required by the ND syntax. I've seen it for just a minute by now, so apparently, I cannot give much advice here... ;)

Thanks, I will start digging. Do you suggest to open a draft PR once I got some of the implementation? Then we can figure out if it's right way or not since I'm foreign to the repo.

pbodnar commented 1 year ago

Do you suggest to open a draft PR once I got some of the implementation? Then we can figure out if it's right way or not since I'm foreign to the repo.

Sure, you can open a PR or even draft PR if you need some feedback sooner. :) Just be sure to follow the guidelines and give a unique name to your branch - e.g. feat-191-nd-renderer in this case.

Also I can't promise someone will give you feedback quickly - I'm maintaining mistletoe in my free time and there are already some prioritized issues on the way (some are not even described here yet)...

eminakgun commented 1 year ago

Alright, thanks