jsii-rosetta does not transliterate submodule READMEs

[Chriscbr]

🐛 Bug Report

Affected Languages

• TypeScript or Javascript
• Python
• Java
• .NET (C#, F#, ...)
• Go

General Information

• JSII Version: 1.53.0
• Platform: macOS 11.6.2

What is the problem?

jsii-rosetta does not seem to be transliterating submodule READMEs. This issue popped up in jsii-docgen as it takes a dependency on jsii-rosetta.

I wasn't able to write up a repro with just jsii-rosetta by itself, but here is an example repro with jsii-docgen@6.1.0:

const fs = require("fs");
const { Language, Documentation } = require("./lib");

async function main() {
  const docs = await Documentation.forPackage('aws-cdk-lib@2.10.0');
  const markdown = await docs.toMarkdown({
    language: Language.PYTHON,
    submodule: "aws_s3",
  });
  fs.writeFileSync("python.md", markdown.render());
}

void main();

If you look here at our code that calls jsii-rosetta, it looks like it could be doing something sneaky where it transliterates just the top-level assembly: https://github.com/cdklabs/jsii-docgen/blob/6a13c8bc60b3dee45c8d18ea581d3b8169c65a37/src/docgen/view/documentation.ts#L320-L333

But since aws-cdk-lib just has a single assembly file I believe it should get transliterated by this API call. But I'm not sure / it's possible maybe jsii-docgen is loading the assembly incorrectly.

Verbose Log

N/A

[agdimech]

I did a little digging and from what I understand the transliterate function only caters for translating the root README as per: https://github.com/aws/jsii/blob/main/packages/jsii-rosetta/lib/commands/transliterate.ts#L89

If you modify the code as follow it seems to resolve the issue although i'm not too sure if we need to support nesting more than 1 level deep. If this is the case it should be pretty easy to modify this into a recursive function.

if (result.readme?.markdown) {
        result.readme.markdown = rosetta.translateSnippetsInMarkdown({ api: 'moduleReadme', moduleFqn: result.name }, result.readme.markdown, language, true);
        Object.entries(result?.submodules)?.forEach(([k, v]) => {
            if (v?.readme?.markdown) {
                v.readme.markdown = rosetta.translateSnippetsInMarkdown({ api: 'moduleReadme', moduleFqn: k }, v.readme.markdown, language, true /* strict */);
            }
        });
}

I also notice that @example blocks are not getting emitted in jsii-docgen (although they are getting transpiled correctly from what I can tell.

[agdimech]

Any movement on this?