Docgen

[prestwich]

We have natspec, JSDoc, docstrings, etc. We need a static site build process that's coherent

[barbaraliau]

Maybe this? https://www.naturaldocs.org/about/

[prestwich]

@barbaraliau we already have natspec in solidity, JSDoc in JS, docstrings in Python, and the correct comment style in golang, I think we need like a makefile that generates everything and throws it into jekyll or something? 🤔

[barbaraliau]

They would all have to be converted into markdown. Jekyll needs liquid, markdown, or html/css, and markdown would be the easiest. I think there are enough packages out there that can be frankensteined together with a makefile. Would still need to construct the Jekyll site with a template. A better long term solution would be to manually build out comprehensive docs. Code comment documentation isn’t necessarily the best for user documentation. There are no use cases and often times explanations aren’t as thorough.

…

On Wed, Oct 23, 2019 at 12:28 James Prestwich ***@***.***> wrote: @barbaraliau <https://github.com/barbaraliau> we already have natspec in solidity, JSDoc in JS, docstrings in Python, and the correct comment style in golang, I think we need like a makefile that generates everything and throws it into jekyll or something? 🤔 — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#76?email_source=notifications&email_token=ACOMYV4DPZWN2ESD7TSNEQ3QQCJUNA5CNFSM4JDYM4J2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOECCNKZA#issuecomment-545576292>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACOMYVYUOWOUPIME7U2LY4DQQCJUNANCNFSM4JDYM4JQ> .

[prestwich]

So I think there are markdown generators for sphinx/autodoc (python) and jsdoc, unsure about godoc or rustdoc or natspec

[barbaraliau]

I’ve found generators for python, js, and go. Not sure about rust or natspec

…

On Sat, Oct 26, 2019 at 13:38 James Prestwich ***@***.***> wrote: So I think there are markdown generators for sphinx/autodoc (python) and jsdoc, unsure about godoc or rustdoc or natspec — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#76?email_source=notifications&email_token=ACOMYV65VI3XHCVFFMIBKSDQQSMDJA5CNFSM4JDYM4J2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOECKPMEA#issuecomment-546633232>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACOMYV4OKCSACHCOI4PZ2HTQQSMDJANCNFSM4JDYM4JQ> .