Eslint-plugin-jsdoc: Make `create-readme` part of test

[golopot]

I find the current workflow of generating readme in post-commit sligtly cumbersome. 1. The commit docs: generate docs is noisy. 2. Somehow the post-commit script will fail if I am not in the branch master.

How about this workflow:

1. Contributor do their work and run test.
2. Test script generate README (without writing to disk), and check that the generated readme is identical to /README.md. If the REAMDE is not up to date, fail test with the message: Please run "npm run create-readme" to update the docs..
3. Contributor run npm run create-readme. This script generate README and write it to disk.

This workflow has the benefit that updatedness of README is tested in CI.

What do yo think?

[gajus]

I agree that the current approach is noisy. This sounds reasonable. Are you available to raise a PR?

[golopot]

Yes I am willing to make a a PR.

[gajus]

This can be also done using Gitdown --check flag now.

See: https://github.com/gajus/gitdown#automating-gitdown

[golopot]

The docs generation has a post step add-assertions, so it seems that gitdown --check will not work here.

[golopot]

@gajus if you are willing to take over the pr, feel free to do so.

[gajus]

The docs generation has a post step add-assertions, so it seems that gitdown --check will not work here.

Good point!

Please continue and ignore me.

[golopot]

There are these approaches:

1. In pre-commit hook, run a script generate-readme that will write generated readme and git add it.
2. In pre-push hook, run a script check-readme that will test if readme if up to date. When failed, ask people to run generate-readme.
3. Test whether readme is up to date in npm test in mocha. When failed, ask people to run generate-readme.

[brettz9]

If I am debugging and running multiple tests, I don't want to have the extra time taken out for the readme to be checked or built. If that option were chosen, I'd at least like to see npm scripts made available to be able to bypass it (whether testing with full coverage or without).

As long as it is not a post-commit hook as it is now (which my git client, in using --no-verify, Husky does not allow to disable), I am good with pre-commit (which my git client can disable) or pre-push (which I can avoid pushing until ready).

Of these choices, I think pre-push may be better for me, as I am personally more likely to accidentally commit with checks when I don't want them. There's no need for the docs to be added around commit time, I think, as building the readme has no information crucial to debugging, so pre-push seems to make the most sense to me personally.

[gajus]

:tada: This issue has been resolved in version 15.5.4 :tada:

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot :package::rocket: