docs: improve documentation related to File templates feature

[Florence-Njeri]

Description
Improve documentation related to File templates feature:

• Separate nunjucks and react render engine file template docs
• Link a real life example of react render engine file template in use

Related issue(s)
Resolves #1199

[aeworxet]

@asyncapi/bounty_team

[Gmin2]

LGTM

just one point you can add more examples

[derberg]

@Gmin2 please suggest one

[changeset-bot]

⚠️ No Changeset found

Latest commit: 8ef5496

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[derberg]

@Gmin2 kind reminder

[Gmin2]

There could be an example of generating with varied content based on different components

import { File } from '@asyncapi/generator-react-sdk';

export default function({ asyncapi }) {
  const files = [];

  // Generate files for channels
  asyncapi.channels().forEach((channel, channelName) => {
    files.push(
      <File name={`channels/${channelName}.md`}>
        # Channel: {channelName}

        Description: {channel.description() || 'No description provided'}

        ## Operations
        {channel.publish() && <div>Publish: {channel.publish().summary()}</div>}
        {channel.subscribe() && <div>Subscribe: {channel.subscribe().summary()}</div>}
      </File>
    );
  });
  return files
  }

other then that looks fine

[Florence-Njeri]

Hey @Gmin2 I have updated the PR

[Gmin2]

LGTM

[derberg]

folks we need an example that is valid. Provided example is not valid and looks like generated with AI, as it is inventing not existing features and using old API.

it is critical to always run examples manually before they are added to docs - no matter if written by ChatGPT or a human (never trust an engineer). Since we have https://github.com/asyncapi/generator/tree/master/apps/generator/test/test-templates/react-template/template in the generator now, it should be as simple as locally adding new file with an example, then you run the generation with CLI and see the result

here is a simplified version of the example:

import { File, Text } from "@asyncapi/generator-react-sdk";

export default function ({ asyncapi }) {
  const files = [];

  // Generate files for channels
  asyncapi.channels().forEach((channel) => {
    const channelName = channel.id();

    files.push(
      <File name={`${channelName}.md`}>
        <Text newLines={2}># Channel: {channelName}</Text>
        <Text>
          {channel.hasDescription() && `${channel.description()}`}
        </Text>
      </File>
    );
  });
  return files;
}

it shows:

• how multiline files generation must be handled with Text component, otherwise all gets generated as one line
• it shows how to work with new API of the parser - more API details in https://github.com/asyncapi/parser-api/blob/master/docs/api.md
• <File name={channels/${channelName}.md}> will not work, you will get an error. If you want to generate channel MD files in channels directory, you need to put template file in channels directory

@Gmin2 your example is good from idea point of view, so now just please take my sample end extend with part where you render operations information (forget about publish and subscribe, it is not there in new AsyncAPI anymore)

[Florence-Njeri]

Hey @derberg @Gmin2 I have updated the PR with the up-to-date code snippet. Please help me re-review. Thank you!

[derberg]

schemas is not an array but a map, so like I suggest in my previous comment to the PR, better use forEach

and yeah, you need to manually test if file is working, as this way you would know something is wrong

during generation I get Generator Error: object is not iterable (cannot read property Symbol(Symbol.iterator))

btw, this example also needs import { File, Text } from "@asyncapi/generator-react-sdk";

[Florence-Njeri]

Hey @derberg I fixed the code. Please take another look

[sonarcloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud

[derberg]

I updated schema example as it was invalid. Without checking examples manually, we should not put them in docs as they are not helpful and only confuse

[derberg]

/rtm