docs: improve documentation related to File templates feature

Florence-Njeri commented 3 months ago

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 commented 3 months ago

@asyncapi/bounty_team

derberg commented 3 months ago

@Gmin2 please suggest one

changeset-bot[bot] commented 3 months ago

⚠️ No Changeset found

Latest commit: 8ef5496be4fd9a5bf8d5e24c4ce812a697479074

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 commented 3 months ago

@Gmin2 kind reminder

Florence-Njeri commented 2 months ago

Hey @Gmin2 I have updated the PR

derberg commented 2 months ago

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 commented 2 months ago

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

Florence-Njeri commented 2 months ago

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