Current Docusaurus support?

[vvolhejn]

Hi, I stumbled upon this library while looking for a tool to add a Python API reference to our Docusaurus docs page. I read in the README that pydoc-markdown is switching to Novella for rendering, but Novella templates are only available for MkDocs and Hugo. What is the status of Docusaurus support at the moment? How difficult would it be to get pydoc-markdown to render my docs into Docusaurus? Thanks!

[rabernat]

I am also interested in this question. I am currently using the legacy pydoc-markdown.yml approach with docusaurus.

[abaiju15]

@rabernat do you have this legacy approach publicly available somewhere? We're looking to do the same thing with Docusaurus and would love to get started with something for our first iteration.

[NiklasRosenstein]

Hey folks 👋 Sorry for the long silence on this topic.

I think that using Novella to generate the documentation is superior due to the amount of control that it gives you. You can place API documentation and other Markdown preprocessing commands inline with the rest of your documentation.

Now I have to admit I am less sure how we can make this work with Docusaurus. It's quite trivial for Mkdocs and Hugo since their input is mostly just Markdown files, but Docusaurus is basically a JavaScript project. Novella copies contents from your current directory into a temporary build directory, and that may be less feasible with Docusaurus because of node_modules/ which is usually rather large. Though we might be able to work that out with a symlink to node_modules/ in the temporary build directory?

Anyway, an alternative that I've been thinking about would be that if used with Docusaurus, Novella could instead generate .md files from another set of Markdown source files, which could either live as siblings in the source tree (for example with a .raw.md suffix) or live elsewhere in the source tree and Novella writes the rendered files where Docusaurus expects them to be.

What do you guys think? Or is there a strong preference leaning on the legacy YAML workflow?

[vvolhejn]

Hi, I'm no longer working on this. I ended up going with mkdocstrings because it seemed more mature and maintained. mkdocstrings doesn't have Docusaurus support either, and the solution that I ended up with was something like the "alternative" that you describe.

I have a Python script that takes raw markdown files with python: some.module.to.get.documentation.for directives and replaces these directives with HTML documentation generated via mkdocstrings. The results are copied into a new directory, docs_generated/. I run this script when I build Docusurus by using spawnSync in docusaurus.config.js. Then Docusaurus proceeds as usual using the files from docs_generated/.

This works, but has the disadvantage of Docusaurus' hot-module reloading not working, since it's watching docs_generated/ and not the original docs/.

I tried more sophisticated approaches that would fix this, but I couldn't get it working easily. See https://github.com/facebook/docusaurus/discussions/8497