feat: automatically generate docs #318

AceTheCreator · 2022-06-06T14:09:16Z

Description
This PR provides a way to automatically generate docs

It generates docs in a folder inside the project. Fully configurable from the glee.config.js file, like the path to the folder and the Generator template to use. We can default to docs and the https://github.com/asyncapi/markdown-template/.

Related issue(s)
Resolves #261

…rator

github-actions

Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

coveralls · 2022-06-06T14:50:51Z

Pull Request Test Coverage Report for Build 3893317675

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

For more information on this, see Tracking coverage changes with pull request builds.
To avoid this issue with future PRs, see these Recommended CI Configurations.
For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

3 of 11 (27.27%) changed or added relevant lines in 1 file are covered.
No unchanged relevant lines lost coverage.
Overall coverage decreased (-17.7%) to 68.861%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
src/lib/docs.ts	3	11	27.27%

Totals
Change from base Build 3885930737:	-17.7%
Covered Lines:	304
Relevant Lines:	395

💛 - Coveralls

jonaslagoni

Looks good to me, we are only missing a test to ensure it works 🙂 There is a bunch of middleware test you can look for guidance, otherwise let me know if you get stuck or have any questions 🙂

AceTheCreator · 2022-06-29T11:02:39Z

Looks good to me, we are only missing a test to ensure it works slightly_smiling_face There is a bunch of middleware test you can look for guidance, otherwise let me know if you get stuck or have any questions slightly_smiling_face

@jonaslagoni please kindly review this PR :)

magicmatatjahu · 2022-06-29T11:06:34Z

test/middlewares/generateDocs.test.ts

+    }
+
+    expect(err).toBeUndefined();
+    fs.emptyDirSync(testDir);


Please at the end remove the testDir dir, not only remove content from it.

@magicmatatjahu what do you mean by "not only remove content from it"?

Read that https://github.com/jprichardson/node-fs-extra/blob/master/docs/emptyDir-sync.md. You should remove dir.

Ok.. my fault. You shouldn't. Don't focus on my previous comments.

Okay 😂. Is the PR okay?

I don't know if PR is okay, but that test is.

fmvilas

Left a couple of comments. I think this PR could be simpler. If I'm understanding correctly, you don't need the readGleeConfig util function. We already have the initializeConfig function that does the same and it's actually doing it with the config only.

fmvilas · 2022-07-05T05:37:54Z

src/index.ts

@@ -41,7 +44,7 @@ export default async function GleeAppInitializer () {
    showAppDir: GLEE_PROJECT_DIR !== process.cwd(),
    showFunctionsDir: GLEE_FUNCTIONS_DIR !== resolve(GLEE_DIR, 'functions'),
  })
-
+  const gleeDocs = await readGleeConfig(GLEE_CONFIG_FILE_PATH)


I don't think you need the readGleeConfig function. You already have the config loaded a few lines before.

fmvilas · 2022-07-05T05:39:25Z

src/middlewares/generateDocs.ts

+    )
+    return 'done'
+  } catch (error) {
+    logLineWithIcon(


You can use this instead: https://github.com/asyncapi/glee/blob/master/src/lib/logger.ts#L123.

@fmvilas I just updated the PR. Kindly review it :)

fmvilas · 2022-07-05T13:45:59Z

src/index.ts

@@ -120,6 +121,7 @@ export default async function GleeAppInitializer () {
  })

  app.on('adapter:server:ready', (e: EnrichedEvent) => {
+    generateDocs(parsedAsyncAPI, config, null)


Why here? If we generate docs on "adapter:server:ready", it will only work for WebSocket and HTTP servers but not for clients (MQTT, Kafka, etc.). I think it should be generated as soon as possible and not necessarily when an event happens.

fmvilas · 2022-07-05T13:49:05Z

src/middlewares/generateDocs.ts

+    await generator.generateFromString(JSON.stringify(resolvedData))
+    logLineWithIcon(
+      ':zap:',
+      'Successfully generated docs for your specification'


"specification" = https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md
"document" = https://github.com/asyncapi/spec/blob/master/examples/simple.yml

People don't have specs but AsyncAPI documents. I'd keep it simpler and rephrase it as:

Suggested change

'Successfully generated docs for your specification'

'Successfully generated docs'

fmvilas · 2022-07-05T13:53:06Z

src/middlewares/generateDocs.ts

+    logErrorLine(
+      `Failed to generate docs for your specs due to the following reason: ${error}`,
+    )


If you're going to log the reason, i.e., the full error, I recommend you use logError. Have a look at the logger.ts file and get familiar with the stuff there 😄

Suggested change

logErrorLine(

`Failed to generate docs for your specs due to the following reason: ${error}`,

)

logErrorLine('Failed to generate docs...')

logError(error)

fmvilas · 2022-07-05T13:53:36Z

test/lib/util.test.ts

@@ -49,4 +51,27 @@ describe('util', () => {
      expect(functionEvent.glee).toBe(glee)
    })
  })
+  describe('readGleeConfig', () => {


🚜 ...
😄

@fmvilas I also didn't get the message you're trying to pass here 😂

hahaha I knew this can happen but I like to comment like this when something needs to be removed
😄 We're not using this function anymore, right?

Yes, you're right :)

fmvilas · 2022-07-05T13:56:41Z

test/middlewares/generateDocs.test.ts

+  it('should generate documentation', async () => {
+    const testDir = tmpdir() + `/${CONFIG_TEST_DATA.generator.folder}`;
+    fs.emptyDirSync(testDir);
+    let err: Error | undefined = undefined;


I think you can do something like this:

Suggested change

let err: Error | undefined = undefined;

let err?: Error

or like this, I can't remember:

Suggested change

let err: Error | undefined = undefined;

let err: Error?

@fmvilas I don't think I understand what you're trying to do here but it seems your code snippet is wrong :)

Mind explaining what you're trying to achieve with that snippet?

I was trying to do something like this: https://www.typescriptlang.org/docs/handbook/advanced-types.html#optional-parameters-and-properties. But it looks like it only works on parameters and object properties 🤦

In any case, you can simplify it like this:

Suggested change

let err: Error | undefined = undefined;

let err: Error | undefined

test/middlewares/generateDocs.test.ts

fmvilas · 2022-12-16T12:44:55Z

src/lib/docs.ts

+
+export default async (spec, config, resDir) => {
+  const configData = config.docs
+  if (configData?.enabled) {


With this check, docs will only be generated if we add this configuration to the config file. It would be awesome if, by default, it generated docs and then people can disable it if they want to. So maybe it should be configData?.disabled instead? Folder can default to docs and template to @asyncapi/markdown-template.

Why should it generate if it says configData?.disabled ? isn't that saying generate if disabled?

shouldn't i be doing !configData || configData?.enabled?

AceTheCreator · 2022-12-19T10:53:57Z

src/lib/docs.ts

+
+export default async (spec, config, resDir) => {
+  const configData = config.docs
+  if (!configData || configData?.enabled) {


Something like this @fmvilas

What about the case when configData exists but enabled is not defined? It should still work but with this check it won't. The reason I said to use disabled instead is that you can easily check for it like this:

if (configData?.disabled) return

This way, you early return only when you find that disabled is true.

Alternatively, you can check for this:

if (configData?.enabled === false) return

That should work as well, I think.

But seems more logical to me that, since the default is that it generates docs, you only go there when you want to disable it or when you want to change the template/folder.

Ah! Now I understand your point @fmvilas

Updated the PR @fmvilas. wyt?

KhudaDad414

LGTM! left some suggestions.

KhudaDad414 · 2022-12-19T12:33:34Z

docs/config-file.md

+      enabled: true // Enable/Disable documentation generation
+      folder: 'docs' // Folder where you want the output of your docs to reside.
+      template: '@asyncapi/markdown-template' // Type of template you want to use.
+    }


Suggested change

enabled: true // Enable/Disable documentation generation

folder: 'docs' // Folder where you want the output of your docs to reside.

template: '@asyncapi/markdown-template' // Type of template you want to use.

}

enabled: true, // Enable/Disable documentation generation

folder: 'docs', // Folder where you want the output of your docs to reside.

template: '@asyncapi/markdown-template' // Type of template you want to use.

}

KhudaDad414 · 2022-12-19T12:34:53Z

package.json

@@ -36,6 +36,8 @@
  "license": "Apache-2.0",
  "dependencies": {
    "@asyncapi/generator": "^1.9.3",


can we safely bump up the generator version here? 🤔 getting some incompatibility errors with this version.

Thanks for the review @KhudaDad414

KhudaDad414

🚢 🙇

AceTheCreator · 2022-12-20T12:07:30Z

@fmvilas @Souvikns any other suggestions?

…ocs_generator

AceTheCreator · 2023-01-10T10:12:32Z

Pinging you all for visibility @fmvilas @KhudaDad414 @Souvikns

…ocs_generator

sonarqubecloud · 2023-01-11T13:35:55Z

Kudos, SonarCloud Quality Gate passed!

0 Bugs
0 Vulnerabilities
0 Security Hotspots
1 Code Smell

No Coverage information
0.0% Duplication

AceTheCreator · 2023-01-11T13:46:27Z

Updated the ReadME @fmvilas. wyt?

fmvilas

LGTM 👍

fmvilas · 2023-01-11T16:15:53Z

@jonaslagoni will have to approve too.

AceTheCreator · 2023-01-12T09:38:31Z

/rtm

asyncapi-bot · 2023-01-12T09:46:06Z

🎉 This PR is included in version 0.13.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

AceTheCreator added 4 commits May 30, 2022 23:25

added docs generator to default docs folder

b07d18e

Implemented glee configuration read feat

db2dbf3

update generateDocs middleware

4fc3e93

Merge branch 'master' of github.com:AceTheCreator/glee into docs_gene…

5f47f7b

…rator

AceTheCreator requested review from fmvilas, jonaslagoni and asyncapi-bot-eve as code owners June 6, 2022 14:09

github-actions bot reviewed Jun 6, 2022

View reviewed changes

fixed code smell :)

e5d6f9d

jonaslagoni suggested changes Jun 7, 2022

View reviewed changes

AceTheCreator added 9 commits June 8, 2022 10:55

moved glee read config to utils

c5f99bc

tested glee file path successfully

8893b57

added test coverage for generateDocs

4e8debf

.

c715a94

.

6c0fe3a

.

5758ec0

testing generator failure

6e603c0

changed to html-template

69fc4c9

fixed docs generator test failure

fe085f6

magicmatatjahu reviewed Jun 29, 2022

View reviewed changes

fmvilas requested changes Jul 5, 2022

View reviewed changes

AceTheCreator added 4 commits July 5, 2022 10:51

removed the readGleeConfig function

5c04e89

Used the existing glee config provided

c24a82b

added logError line for error in generateDocs function

30432a5

.

2fc4b07

fmvilas requested changes Jul 5, 2022

View reviewed changes

AceTheCreator added 2 commits July 5, 2022 17:39

triggered generateDocs function asap

0dfd90b

used logError func for generateDocs error logging

53b3ce1

AceTheCreator added 2 commits December 15, 2022 20:16

fixed config doc mistake

7dfec34

.

3201cac

Souvikns previously approved these changes Dec 16, 2022

View reviewed changes

fmvilas requested changes Dec 16, 2022

View reviewed changes

AceTheCreator dismissed Souvikns’s stale review via 25be26e December 19, 2022 10:53

updated docs config

25be26e

AceTheCreator commented Dec 19, 2022

View reviewed changes

KhudaDad414 requested changes Dec 19, 2022

View reviewed changes

updated the generator package

b6bffaa

KhudaDad414 previously approved these changes Dec 19, 2022

View reviewed changes

enhanced docs generation function

56b9863

AceTheCreator dismissed KhudaDad414’s stale review via cf74791 December 23, 2022 09:49

Merge branch 'master' of https://github.com/AceTheCreator/glee into d…

cf74791

…ocs_generator

Souvikns previously approved these changes Jan 10, 2023

View reviewed changes

AceTheCreator added 2 commits January 11, 2023 13:21

Merge branch 'master' of https://github.com/AceTheCreator/glee into d…

b1ca08d

…ocs_generator

added glee docs

476883b

AceTheCreator dismissed Souvikns’s stale review via 476883b January 11, 2023 13:35

fmvilas approved these changes Jan 11, 2023

View reviewed changes

jonaslagoni approved these changes Jan 11, 2023

View reviewed changes

asyncapi-bot added the ready-to-merge label Jan 12, 2023

asyncapi-bot merged commit e7ada8b into asyncapi:master Jan 12, 2023

AceTheCreator deleted the docs_generator branch January 12, 2023 09:40

asyncapi-bot added the released label Jan 12, 2023

	'Successfully generated docs for your specification'
	'Successfully generated docs'

	let err: Error \| undefined = undefined;
	let err: Error \| undefined

feat: automatically generate docs #318

feat: automatically generate docs #318

Conversation

AceTheCreator commented Jun 6, 2022

github-actions bot left a comment

Choose a reason for hiding this comment

coveralls commented Jun 6, 2022 • edited Loading

Pull Request Test Coverage Report for Build 3893317675

Warning: This coverage report may be inaccurate.

Details

💛 - Coveralls

jonaslagoni left a comment

Choose a reason for hiding this comment

AceTheCreator commented Jun 29, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fmvilas left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fmvilas Dec 23, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

KhudaDad414 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

KhudaDad414 left a comment

Choose a reason for hiding this comment

AceTheCreator commented Dec 20, 2022

AceTheCreator commented Jan 10, 2023

sonarqubecloud bot commented Jan 11, 2023

AceTheCreator commented Jan 11, 2023

fmvilas left a comment

Choose a reason for hiding this comment

fmvilas commented Jan 11, 2023

AceTheCreator commented Jan 12, 2023

asyncapi-bot commented Jan 12, 2023

coveralls commented Jun 6, 2022 •

edited

Loading

fmvilas Dec 23, 2022 •

edited

Loading