Generating (Python) API documentation with govuk-eleventy-plugin

[michalc]

Hi 👋 ,

Firstly, thanks for a great plugin - it's been really useful for a few projects, e.g. https://pg-bulk-ingest.docs.trade.gov.uk/ and https://stream-unzip.docs.trade.gov.uk/

One thing though that I'm not quite sure how to do is integrating govuk-eleventy-plugin / 11ty with some sort of system for generating API documentation from source code, and specifically for Python, say using https://github.com/pdoc3/pdoc.

I wonder if anyone has any tips/suggestions on how to tackle this?

Thanks!

Michal

[michalc]

So have the seeds of a solution using https://github.com/NiklasRosenstein/pydoc-markdown, which can be called as a process and outputs to stdout to cross the Javascript/Python boundary

So in eleventy.config.js can have something like this:

const util = require('util');
const execFile = util.promisify(require('child_process').execFile);
eleventyConfig.addGlobalData("api", async () => {
    const { stdout, stderr } = await execFile('pydoc-markdown', ['-p', 'stream_unzip'])
    return stdout;
});

And this then makes api available in content files, just as {{ api }}.

And if more customisation is needed, pydoc-markdown offers more "raw" JSON output:

eleventyConfig.addGlobalData("api", async () => {
    const { stdout, stderr } = await execFile('pydoc-markdown',  ['-p', 'stream_zip', '--dump'])
    return JSON.parse(stdout)
});

And then can be used in content files more manually

{%- for member in api["members"] -%}
{{ member["name"] }}<br>
{%- endfor -%}<br>

[1lliter8]

Griffe, which mkdocstrings uses, might be a better way of getting that JSON.