docs(repo): update rulesets docs

[heitortsergent]

Fixes #2231.

Preview link:

• https://docs.stoplight.io/docs/spectral/branches/docs%2Freorganize-rulesets/01baf06bdd05a-create-a-ruleset (former Rulesets page)
• https://docs.stoplight.io/docs/spectral/branches/docs%2Freorganize-rulesets/e5b9616d6d50c-rulesets (former Custom Rulesets page)

Checklist

• Tests added / updated
• Docs added / updated

Does this PR introduce a breaking change?

• Yes
• No

[heitortsergent]

@philsturgeon would you mind taking a look at this and telling me what you think? I took a pass at reorganizing the Rulesets and Custom Rulesets page.

I think there's still some work to do here in the Custom Rulesets Overview page (some reorganizing and rewriting), but want to get your thoughts before I make more changes.

This link should work to see it in the docs view: https://docs.stoplight.io/docs/spectral/branches/docs%2Freorganize-rulesets/01baf06bdd05a-rulesets

[philsturgeon]

Custom Rulesets starts with this which no longer makes sense in the move:

Customizing existing rulesets might be all you need at first, but at some point, you will want to make a custom ruleset.

Let's start from scratch.

Lets look through the various keywrods that make up a ruleset, so you can learn to tweak a distributed ruleset to work for you, or make your own ruleset from scratch to power your organizations API Style Guide or some other custom situation.

[philsturgeon]

Generally this is looking amazing! Using a group is a fantastic way to break it down.

[philsturgeon]

Btw I noticed an old mistake I made, I had given: $.paths.[*][get,post,put,delete,options] but it should be given: $.paths[*][get,post,put,delete,options].

From @P0lip:

$.paths.[*] acts as $.paths..[*] so it goes deep - it's incorrect if you only want to target an operation object.

[heitortsergent]

@philsturgeon thanks!! I fixed the given example you mentioned.

I'll go ahead and update the intro to Custom Rulesets and make some more changes then. I'll tag you again once it's ready for another look. :)

[heitortsergent]

@philsturgeon I think it's ready for another look if you have some time? :D

• Renamed the Rulesets page to Create a Ruleset - I think that makes more sense in terms of that page being a part of the "Getting Started" section
• Renamed "Custom Rulesets" to "Rulesets"
• Updated the intro to "Rulesets" page to emphasize "Custom Ruleset" a bit less (like you mentioned in your previous comment)
• Split up "Rules" into its own separate page - I was struggling a little bit with having the Ruleset Properties and Rule Properties in the same page, I think this might work better

I don't love having the Rulesets group now with: Overview, Rules, and then specific pages for certain Ruleset Properties (Aliases, etc.), but I'm not sure having a subgroup in there is a good idea... I'm thinking if this seems like a better organization, I could also stop at this point for this PR and just fix the links, and we can play around with a bit more in a separate PR.

Let me know what you think! 🙏

[pamgoodrich]

Great updates!

[pamgoodrich]

I think I asked before. Do we need the v6.0 here?

[heitortsergent]

You did, and I tagged other folks in that comment but didn't get a reply, so it stayed in there since I wasn't sure if it was ok to remove.

[stoplight-bot]

🎉 This PR is included in version 6.7.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀