Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Markdoc: Stripe's Markdown-based authoring framework

markdoc.io

Post reply on HN
Print view View original

151–157 of 157 posts

Re: Markdoc: Stripe's Markdown-based authoring framework

#151

Post by squidfunk »

d4rkp4ttern wrote: post #148
_miau_hoch2 wrote: post #64

For anyone looking for a doc generation tool: I was lately evaluating several tools like VuePress, Docusaurus and AsciiDoc. I ended up using Mkdocs Material ( https://squidfunk.github.io/mkdocs-material/ ). If you haven't already, have a look. I think it is pretty impressive. From tags, tabs to the fantastic built-in search ...

Does Mkdocs have functionality to auto-generate docs from docstrings? I’ve been using Sphinx with RTD (ReadTheDocs) theme for python code. Wondering if Mkdocs can somehow be better.

Author of Material for MkDocs here. MkDocstrings [1] implements automatic generation of reference documentation from sources. It's language-agnostic, actively maintained and currently supports Python [2] and Crystal [3]. It also integrates nicely with Material for MkDocs.

[1]: https://mkdocstrings.github.io/

[2]: https://github.com/mkdocstrings/python

[3]: https://github.com/mkdocstrings/crystal

Re: Markdoc: Stripe's Markdown-based authoring framework

#152

Post by d4rkp4ttern »

squidfunk wrote: post #151
d4rkp4ttern wrote: post #148

Earlier quoted context omitted.

Does Mkdocs have functionality to auto-generate docs from docstrings? I’ve been using Sphinx with RTD (ReadTheDocs) theme for python code. Wondering if Mkdocs can somehow be better.

Author of Material for MkDocs here. MkDocstrings [1] implements automatic generation of reference documentation from sources. It's language-agnostic, actively maintained and currently supports Python [2] and Crystal [3]. It also integrates nicely with Material for MkDocs. [1]: https://mkdocstrings.github.io/ [2]: https://github.com/mkdocstrings/python [3]: https://github.com/mkdocstrings/crystal

This is great, thank you.

Re: Markdoc: Stripe's Markdown-based authoring framework

#153

Post by d4rkp4ttern »

squidfunk wrote: post #151
d4rkp4ttern wrote: post #148

Earlier quoted context omitted.

Does Mkdocs have functionality to auto-generate docs from docstrings? I’ve been using Sphinx with RTD (ReadTheDocs) theme for python code. Wondering if Mkdocs can somehow be better.

Author of Material for MkDocs here. MkDocstrings [1] implements automatic generation of reference documentation from sources. It's language-agnostic, actively maintained and currently supports Python [2] and Crystal [3]. It also integrates nicely with Material for MkDocs. [1]: https://mkdocstrings.github.io/ [2]: https://github.com/mkdocstrings/python [3]: https://github.com/mkdocstrings/crystal

Another important requirement for me is support for Math notation in docstrings and elsewhere. Looks like MkDocs supports mathjax?

https://squidfunk.github.io/mkdocs-material/reference/mathja...

Re: Markdoc: Stripe's Markdown-based authoring framework

#154

Post by squidfunk »

d4rkp4ttern wrote: post #153
squidfunk wrote: post #151

Earlier quoted context omitted.

Author of Material for MkDocs here. MkDocstrings [1] implements automatic generation of reference documentation from sources. It's language-agnostic, actively maintained and currently supports Python [2] and Crystal [3]. It also integrates nicely with Material for MkDocs. [1]: https://mkdocstrings.github.io/ [2]: https://github.com/mkdocstrings/python [3]: https://github.com/mkdocstrings/crystal

Another important requirement for me is support for Math notation in docstrings and elsewhere. Looks like MkDocs supports mathjax? https://squidfunk.github.io/mkdocs-material/reference/mathja...

Jup, MathJax is supported with minimal setup: https://squidfunk.github.io/mkdocs-material/reference/mathja...

Re: Markdoc: Stripe's Markdown-based authoring framework

#155

Post by d4rkp4ttern »

squidfunk wrote: post #154
d4rkp4ttern wrote: post #153

Earlier quoted context omitted.

Another important requirement for me is support for Math notation in docstrings and elsewhere. Looks like MkDocs supports mathjax? https://squidfunk.github.io/mkdocs-material/reference/mathja...

Jup, MathJax is supported with minimal setup: https://squidfunk.github.io/mkdocs-material/reference/mathja...

Thanks. The MkDocs docs looks great. Would you be able to point to a sample (python) repo that has various configs etc that I can tweak? When starting with Sphinx + ReadTheDocs this was the most time consuming part , it took me several hours hunting down various docs and examples.

Re: Markdoc: Stripe's Markdown-based authoring framework

#156

Post by [deleted] »

squidfunk wrote: post #154
d4rkp4ttern wrote: post #153

Earlier quoted context omitted.

Another important requirement for me is support for Math notation in docstrings and elsewhere. Looks like MkDocs supports mathjax? https://squidfunk.github.io/mkdocs-material/reference/mathja...

Jup, MathJax is supported with minimal setup: https://squidfunk.github.io/mkdocs-material/reference/mathja...

[deleted]

Re: Markdoc: Stripe's Markdown-based authoring framework

#157

Post by squidfunk »

d4rkp4ttern wrote: post #155
squidfunk wrote: post #154

Earlier quoted context omitted.

Jup, MathJax is supported with minimal setup: https://squidfunk.github.io/mkdocs-material/reference/mathja...

Thanks. The MkDocs docs looks great. Would you be able to point to a sample (python) repo that has various configs etc that I can tweak? When starting with Sphinx + ReadTheDocs this was the most time consuming part , it took me several hours hunting down various docs and examples.

I recommend checking the list of OpenSource projects that use Material for MkDocs [1], for example FastAPI [2]. Alternatively, you can clone the Material for MkDocs repository, as the docs are built with itself.

[1] https://github.com/squidfunk/mkdocs-material#trusted-by-

[2] https://github.com/tiangolo/fastapi

Post reply on HN