docgen for python flattens out structs that aren't flattened in codegen

[iliapolo]

The python documentation generated for this code:

export interface SecretValue {
  readonly secret: ISecret;
  readonly key: string;
}

export interface EnvValueFromSecretOptions {
  readonly optional?: boolean;
}

public static fromSecretValue(secretValue: secret.SecretValue, options: EnvValueFromSecretOptions = {}): EnvValue {
  ...
  ...
}

is this:

cdk8s_plus_25.EnvValue.from_secret_value(
  key: str,
  secret: ISecret,
  optional: bool = None
)

Notice how it flattened the first struct argument, even though its not supposed to. The docs should instead be:

cdk8s_plus_25.EnvValue.from_secret_value(
  secret_value: typing.Union["SecretValue", typing.Dict[builtins.str, typing.Any]],
  optional: bool = None
)

originally discussed here: aws/jsii#3883

[iliapolo]

We can consider dropping the Dict from the signature and just mentioning the SecretValue class to avoid overloading the reader. But in any case the current docs are just wrong and result in a jsii error if used as is.