Merge pull request #203 from GetStream/generate-component-docs

feat: Doc comments for components, documentation generated from doc c…

Author: szuperaz

.github/workflows/workflow.yml

@@ -54,7 +54,7 @@ jobs:
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: npx semantic-release
-      - name: Generate service docs
+      - name: Generate docs
         run: |
           npm run generate-docs
       - name: Push to docusaurus

.gitignore

@@ -41,7 +41,8 @@ testem.log
 /typings
 
 # Generated docs
-temp-docs
+temp-service-docs
+temp-component-docs
 docusaurus/docs/Angular/services/*.mdx
 
 # System Files

README.md

@@ -30,15 +30,38 @@ The best way to get started is to follow the [Angular Chat Tutorial](https://get
 Stream is free for most side and hobby projects. To qualify, your project/company must have no more than 5 team members and earn less than $10k in monthly revenue.
 For complete pricing and details visit our [Chat Pricing Page](https://getstream.io/chat/pricing/).
 
+## Docs
+
+The [docs](https://getstream.io/chat/docs/sdk/angular/) provide a brief description about the components and services in the library.
+
+The Angular library is created using the [stream-chat-js](https://github.com/getstream/stream-chat-js) library. For the most common use cases our services should give a nice abstraction over this library, however you might need it for more advanced customization, the [documentation](https://getstream.io/chat/docs/js/) is on our website.
+
+## Contributing
+
+We welcome code changes that improve this library or fix a problem. Please make sure to follow all best practices and add tests, if applicable, before submitting a pull request on GitHub. We are pleased to merge your code into the official repository if it meets a need. Make sure to sign our [Contributor License Agreement (CLA)](https://docs.google.com/forms/d/e/1FAIpQLScFKsKkAJI7mhCr7K9rEIOpqIDThrWxuvxnwUq2XkHyG154vQ/viewform) first. See our license file for more details.
+
+## We are hiring!
+
+We recently closed a [$38 million Series B funding round](https://techcrunch.com/2021/03/04/stream-raises-38m-as-its-chat-and-activity-feed-apis-power-communications-for-1b-users/) and are actively growing.
+Our APIs are used by more than a billion end-users, and by working at Stream, you have the chance to make a huge impact on a team of very strong engineers.
+
+Check out our current openings and apply via [Stream's website](https://getstream.io/team/#jobs).
+
 ## Installation
 
 ### Install with NPM
 
-```
+Run the following command if you are using **Angular 13**:
+
+```shell
 npm install stream-chat-angular @stream-io/stream-chat-css stream-chat @ngx-translate/core
 ```
 
-**Important note** If you are using **Angular 12** you will need to add `--legacy-peer-deps` flag as `@ngx-translate/core`'s newest version only supports Angular 13.
+Run this command if you are using **Angular 12**:
+
+```shell
+npm install stream-chat-angular @stream-io/stream-chat-css stream-chat@5 @ngx-translate/core --legacy-peer-deps
+```
 
 ## Sample App
 
@@ -56,19 +79,12 @@ STREAM_USER_TOKEN=<Your user token>
 
 Run `npm start` and navigate to `http://localhost:4200/`.
 
-## Docs
+## Local development
 
-The [docs](https://getstream.io/chat/docs/sdk/angular/) provide a brief description about the components and services in the library.
-
-The Angular library is created using the [stream-chat-js](https://github.com/getstream/stream-chat-js) library. For the most common use cases our services should give a nice abstraction over this library, however you might need it for more advanced customization, the [documentation](https://getstream.io/chat/docs/js/) is on our website.
+Run `npm install` in the root of the project. You can use the `npm run start:dev` command to start the SampleApp with automatic reloading.
 
-## Contributing
+A note about the documentation:
 
-We welcome code changes that improve this library or fix a problem. Please make sure to follow all best practices and add tests, if applicable, before submitting a pull request on GitHub. We are pleased to merge your code into the official repository if it meets a need. Make sure to sign our [Contributor License Agreement (CLA)](https://docs.google.com/forms/d/e/1FAIpQLScFKsKkAJI7mhCr7K9rEIOpqIDThrWxuvxnwUq2XkHyG154vQ/viewform) first. See our license file for more details.
-
-## We are hiring!
-
-We recently closed a [$38 million Series B funding round](https://techcrunch.com/2021/03/04/stream-raises-38m-as-its-chat-and-activity-feed-apis-power-communications-for-1b-users/) and are actively growing.
-Our APIs are used by more than a billion end-users, and by working at Stream, you have the chance to make a huge impact on a team of very strong engineers.
-
-Check out our current openings and apply via [Stream's website](https://getstream.io/team/#jobs).
+- Documentations for Angular services are generated from doc comments in the source files (not under source control)
+- Documentations for inputs and outputs of Angular components are generated from doc comments in the source files (not under source control)
+- Everything else in the documentation is written in `mdx` files located in the `docusaurus` folder

copy-generated-component-docs.ts

@@ -0,0 +1,90 @@
+const fs = require('fs');
+
+const generatedDocsPath = 'temp-component-docs/classes';
+const componentDocsPath = 'docusaurus/docs/Angular/components';
+const startOfGeneratedContentMark = '[//]: # "Start of generated content"';
+const endOfGeneratedContentMark = '[//]: # "End of generated content"';
+
+const extractProperties = (content: string) => {
+  const lines: string[] = content.split('\n');
+  const startOfPropertiesMark = '## Properties';
+  const endOfPropertiesMark = '## '; // End of properties: next heading
+  const startOfPropertiesLineNumber = lines.indexOf(startOfPropertiesMark);
+  const endOfPropertiesLineNumber = lines.findIndex(
+    (line, index) =>
+      line.startsWith(endOfPropertiesMark) &&
+      index > startOfPropertiesLineNumber
+  );
+
+  if (startOfPropertiesLineNumber === -1) {
+    return [];
+  }
+
+  return lines.filter(
+    (_, lineNumber) =>
+      lineNumber > startOfPropertiesLineNumber &&
+      (endOfPropertiesLineNumber === -1 ||
+        lineNumber < endOfPropertiesLineNumber)
+  );
+};
+
+const insertGeneratedParts = (
+  fileContent: string,
+  generatedContent: string[]
+) => {
+  const lines: string[] = fileContent.split('\n');
+  const startOfGeneratedContentLineNumber = lines.indexOf(
+    startOfGeneratedContentMark
+  );
+  const result = [
+    ...lines.splice(0, startOfGeneratedContentLineNumber + 1),
+    generatedContent.length ? '## Inputs and outputs \n' : '\n',
+    ...generatedContent,
+    ...lines.splice(0),
+  ];
+
+  return result.join('\n');
+};
+
+fs.readdir(generatedDocsPath, (err: any, files: string[]) => {
+  if (err) {
+    throw err;
+  }
+  files.forEach((file) => {
+    fs.readFile(
+      `${generatedDocsPath}/${file}`,
+      'utf8',
+      (err: any, generatedFileContent: string) => {
+        if (err) {
+          throw err;
+        }
+
+        const propertiesContent = extractProperties(generatedFileContent);
+
+        fs.readFile(
+          `${componentDocsPath}/${file}x`,
+          'utf8',
+          (err: any, docFile: any) => {
+            if (err)
+              throw new Error(
+                `${componentDocsPath}/${file}x couldn't be opened, error: ${err}, make sure that this file exists`
+              );
+
+            if (file !== '_category_.json') {
+              const result = insertGeneratedParts(docFile, propertiesContent);
+
+              fs.writeFile(
+                `${componentDocsPath}/${file}x`,
+                result,
+                'utf8',
+                (err: any) => {
+                  if (err) throw err;
+                }
+              );
+            }
+          }
+        );
+      }
+    );
+  });
+});

copy-generated-docs.ts renamed to copy-generated-service-docs.ts

@@ -1,23 +1,25 @@
 const fs = require('fs');
 
-const sourcePath = 'temp-docs/classes';
-const targetPath = 'docusaurus/docs/Angular/services';
+const sourcePath = 'temp-service-docs/classes';
+const serviceDocsTargetPath = 'docusaurus/docs/Angular/services';
 
-fs.readdir(targetPath, (err: any, files: string[]) => {
+// remove docs from the source folder
+fs.readdir(serviceDocsTargetPath, (err: any, files: string[]) => {
   if (err) {
     throw err;
   }
   files.forEach((file) => {
     if (file !== '_category_.json') {
       try {
-        fs.unlinkSync(`${targetPath}/${file}`);
+        fs.unlinkSync(`${serviceDocsTargetPath}/${file}`);
       } catch (err: any) {
         throw err;
       }
     }
   });
 });
 
+// copy generated files
 fs.readdir(sourcePath, (err: any, files: string[]) => {
   if (err) {
     throw err;
@@ -27,6 +29,8 @@ fs.readdir(sourcePath, (err: any, files: string[]) => {
       if (err) {
         throw err;
       }
+
+      // Remove the thre prefix from the title
       const result = data.replace(/# Class:/g, '#');
 
       fs.writeFile(`${sourcePath}/${file}`, result, 'utf8', (err: any) => {
@@ -35,7 +39,7 @@ fs.readdir(sourcePath, (err: any, files: string[]) => {
         }
         fs.copyFile(
           `${sourcePath}/${file}`,
-          `${targetPath}/${file}x`,
+          `${serviceDocsTargetPath}/${file}x`,
           (err: any) => {
             if (err) {
               throw err;

docusaurus/docs/Angular/code-examples/emoji-picker.mdx

@@ -61,7 +61,7 @@ export class AppModule {}
 
 3. Component class
 
-Your emoji picker component should have an input with the type `Subject<string>` to emit the selected emojis. This input will be provided by the [`MessageInput`](../components/message-input.mdx) component.
+Your emoji picker component should have an input with the type `Subject<string>` to emit the selected emojis. This input will be provided by the [`MessageInput`](../components/MessageInputComponent.mdx) component.
 
 We also defined an `isOpened` property that tells if the emoji picker should be opened or closed.
 
@@ -153,7 +153,7 @@ button {
 
 ## Provide your custom template
 
-Let's provide our custom emoji picker template to the [`MessageInput`](../components/message-input.mdx) component:
+Let's provide our custom emoji picker template to the [`MessageInput`](../components/MessageInputComponent.mdx) component:
 
 ```html
 <div id="root">

docusaurus/docs/Angular/components/attachment-list.mdx renamed to docusaurus/docs/Angular/components/AttachmentListComponent.mdx

@@ -1,13 +1,5 @@
----
-id: attachment-list
-sidebar_position: 2
-title: Attachments
----
-
 import AttachmentsScreenshot from "../assets/attachments-screenshot.png";
 
-TEST
-
 The `AttachmentList` compontent displays the attachments of a message. The following attachments are supported:
 
 - Images (including GIFs) are displayed inline
@@ -41,20 +33,5 @@ export class CustomMessageComponent {
 }
 ```
 
-## Inputs
-
-### <div class="label required basic">Required</div> attachments
-
-The attachments to display
-
-| Type                                                                                                              | Default |
-| ----------------------------------------------------------------------------------------------------------------- | ------- |
-| [`Attachment`](https://getstream.io/chat/docs/javascript/message_format/?language=javascript#attachment-format)[] | []      |
-
-### <div class="label required basic">Required</div> messageId
-
-The id of the message the attachments belong to
-
-| Type   |
-| ------ |
-| string |
+[//]: # "Start of generated content"
+[//]: # "End of generated content"

docusaurus/docs/Angular/components/attachment-preview-list.mdx renamed to docusaurus/docs/Angular/components/AttachmentPreviewListComponent.mdx

@@ -1,9 +1,3 @@
----
-id: attachment-preview-list
-sidebar_position: 3
-title: Attachment previews
----
-
 import Screenshot from "../assets/attachment-preview-list-screenshot.png";
 
 The `AttachmentPreviewList` compontent displays a preview of the attachments uploaded to a message. Users can delete attachments using the preview component, or retry upload if it failed previously.
@@ -30,3 +24,6 @@ export class CustomMessageInputComponent {}
 ```
 
 The `AttachmentPreviewList` uses the [`AttachmentService`](../services/AttachmentService.mdx) to display the attachment previews.
+
+[//]: # "Start of generated content"
+[//]: # "End of generated content"

docusaurus/docs/Angular/components/AutocompleteTextareaComponent.mdx

@@ -0,0 +1,37 @@
+The `AutocompleteTextarea` component is used by the [`MessageInput`](./MessageInputComponent.mdx) component to display the input HTML element where users can type their message.
+
+Message send can be triggered with the `Enter` key, new line can be added with the `Shift+Enter` combination.
+
+The `AutocompleteTextarea` extends the funcitonalities of the [`Textarea`](./TextareaComponent.mdx) component with autocomplete features:
+
+- users can mention other users in a message (transliteration is used to support languages with non-Latin characters)
+- users can send commands (for example /giphy)
+
+## Basic usage
+
+You can use the `AutocompleteTextarea` component if you want to create your own message input component to override the default one:
+
+```typescript
+@Component({
+  selector: "app-custom-message-input",
+  template: `
+    <stream-autocomplete-textarea
+      [(value)]="textareaValue"
+      (send)="messageSent()"
+      (userMentions)="mentionedUsers = $event"
+    ></stream-autocomplete-textarea>
+    <!-- Other parts of the custom message input component -->
+  `,
+})
+export class CustomMessageInputComponent {
+  textareaValue = "";
+  mentionedUsers = [];
+
+  messageSent() {
+    // Send your message
+  }
+}
+```
+
+[//]: # "Start of generated content"
+[//]: # "End of generated content"

docusaurus/docs/Angular/components/avatar.mdx renamed to docusaurus/docs/Angular/components/AvatarComponent.mdx

@@ -1,9 +1,3 @@
----
-id: avatar
-sidebar_position: 1
-title: Avatar
----
-
 The `Avatar` component displays the provided image, with fallback to the first letter of the optional name input.
 
 ## Basic Usage
@@ -27,28 +21,5 @@ export class CustomMessageComponent {
 }
 ```
 
-## Inputs
-
-### imageUrl
-
-The URL of the image to be displayed. If the image can't be displayed the first letter of the name input is displayed.
-
-| Type           | Default                   |
-| -------------- | ------------------------- |
-| string \| null | first initial of the name |
-
-### name
-
-An optional name of the image, used for fallback image or image title (if `imageUrl` is provided)
-
-| Type           |
-| -------------- |
-| string \| null |
-
-### size
-
-The size in pixels of the avatar image.
-
-| Type   | Default |
-| ------ | ------- |
-| number | 32px    |
+[//]: # "Start of generated content"
+[//]: # "End of generated content"