docs: Create a shared settings document

[scagood]

This is the final part of #108. Previous parts: #114, #112.

Hopefully this is a better way to document shared options in this package 👀

[scagood]

I am not sure how to avoid this:

`no-extraneous-import` rule doc should have included rule option: include
`no-extraneous-import` rule doc should have included rule option: exclude
`no-extraneous-import` rule doc should have included rule option: replace
`no-extraneous-require` rule doc should have included rule option: include
`no-extraneous-require` rule doc should have included rule option: exclude
`no-extraneous-require` rule doc should have included rule option: replace
`no-unpublished-bin` rule doc should have included rule option: exclude
`no-unpublished-bin` rule doc should have included rule option: replace
`no-unpublished-import` rule doc should have included rule option: exclude
`no-unpublished-import` rule doc should have included rule option: replace
`no-unpublished-require` rule doc should have included rule option: exclude
`no-unpublished-require` rule doc should have included rule option: replace
`shebang` rule doc should have included rule option: include
`shebang` rule doc should have included rule option: exclude
`shebang` rule doc should have included rule option: replace

It seems to be the child options for convertPath
I have referenced the shared settings for the convertPath option in all the files 🤔

[aladdin-add]

@bmish it causes eslint-docs-generator to report an error, when moving the options docs to another page(shared-settings). Is there a way to ignore the error?

I'm glad to help making a PR in eslint-docs-generagor if you want. 😄

[bmish]

Since it looks like the rule options are all mentioned in a shared doc instead, it should be safe for you to use the option --rule-doc-section-options false to disable the check (https://github.com/bmish/eslint-doc-generator#configuration-options).

[scagood]

The issue is that we mention the root option, and reference it, eg in no-extraneous-import:

We reference convertPath docs/rules/no-extraneous-import.md#convertpath and point to the shared setting docs/shared-settings.md#convertpath

The schema is defined here: lib/rules/no-extraneous-import.js#L27-L31

The issue is that the missing options are child properties of convertPath:

• convertPath.include
• convertPath.exclude
• convertPath.replace

`no-extraneous-import` rule doc should have included rule option: include
`no-extraneous-import` rule doc should have included rule option: exclude
`no-extraneous-import` rule doc should have included rule option: replace

[bmish]

The existing eslint-doc-generator option --rule-doc-section-options is all-or-nothing in terms of checking for the options section and any named options it can detect. So with your planned design, you may just have to disable the option. Let me know if you have ideas for more granular options to control these checks.

[aladdin-add]

wonderful job! The option looks useful! 👍

[aladdin-add]

We can turn off this option for now and use that option when it was supported in eslint-doc-generator.
wdyt?

[scagood]

mmm, I don't love the option, as you'd need to be more vigilant in PRs.

If that is fine with you, then we can proceed with the option.

[scagood]

I don't love it, but its disabled here:

2f27eb8 (#115)

[bmish]

@scagood --rule-doc-section-options-depth (as it customizes the existing --rule-doc-section-options option behavior) sounds like an interesting idea. Would you like to open an issue in eslint-doc-generator to suggest it so we can track this? I'm open to considering it if you feel that it's necessary and ideally that it would be useful to more than just this plugin.

In the meantime, you should proceed without this and just disable --rule-doc-section-options for now.

[aladdin-add]

to avoid breaking changes:

• --rule-doc-section-options=true can be treated as depth: Infinity
• --rule-doc-section-options=false as depth: 0