Documentation Rewrite #417
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
tbarn
previously requested changes
Aug 2, 2019
philsturgeon
force-pushed
the
docs/rewrite
branch
from
3e0c592 to
45ede47
Compare
philsturgeon
requested review from
tbarn,
XVincentX,
chris-miaskowski and
P0lip
P0lip
reviewed
Aug 2, 2019
Co-Authored-By: Jakub Rożek <P0lip@users.noreply.github.com>
Co-Authored-By: Jakub Rożek <P0lip@users.noreply.github.com>
|
@tbarn fixed most of it, but what are |
|
Someone asked:
I thought it would be helpful for people writing custom rulesets. |
|
Right but I don’t know what fields this person is talking about. |
|
Anything that goes in these:
|
|
Oooooh ok the way the question was worded by the original person is funny. It’s just whatever is in the target you selected. You select info then all the fields in info are available. I’ll add a note so that’s clear.
…--
Phil Sturgeon
@philsturgeon
On Aug 2, 2019, at 21:58, Taylor Barnett ***@***.***> wrote:
Anything that goes in these:
—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub, or mute the thread.
|
philsturgeon
force-pushed
the
docs/rewrite
branch
from
4174110 to
b813caf
Compare
|
Done!
…--
Phil Sturgeon
@philsturgeon
On Aug 2, 2019, at 21:58, Taylor Barnett ***@***.***> wrote:
Anything that goes in these:
—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub, or mute the thread.
|
|
Looking good. I'll approve if you remove all the occurrences of "just." |
philsturgeon
force-pushed
the
docs/rewrite
branch
from
b813caf to
96421bf
Compare
|
just removed the justs! |
marbemac
previously requested changes
Aug 5, 2019
tbarn
previously approved these changes
Aug 6, 2019
philsturgeon
dismissed stale reviews from tbarn and chris-miaskowski
via
3bbeb6f
philsturgeon
force-pushed
the
docs/rewrite
branch
4 times, most recently
from
de07aa2 to
083a2cb
Compare
philsturgeon
force-pushed
the
docs/rewrite
branch
from
083a2cb to
ff8031f
Compare
|
|
||
| ## Features | ||
|
|
||
| - Create custom rules to lint JSON or YAML objects | ||
| - Ready to use rules to validate and lint OpenAPI v2 _and_ v3 documents | ||
| - Use JSON path to apply rules to specific parts of your objects | ||
| - Built-in set of functions to help [create custom rules](./docs/rulesets.md). Functions include pattern checks, parameter checks, alphabetical ordering, a specified number of characters, provided keys are present in an object, etc. | ||
| - Built-in set of functions to help [create custom rules](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/rulesets.md#adding-a-rule). Functions include pattern checks, parameter checks, alphabetical ordering, a specified number of characters, provided keys are present in an object, etc. |
There was a problem hiding this comment.
Suggested change
| - Built-in set of functions to help [create custom rules](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/rulesets.md#adding-a-rule). Functions include pattern checks, parameter checks, alphabetical ordering, a specified number of characters, provided keys are present in an object, etc. | |
| - Built-in set of functions to help [create custom rules](docs/gh/stoplightio/spectral/docs/getting-started/rulesets.md#adding-a-rule). Functions include pattern checks, parameter checks, alphabetical ordering, a specified number of characters, provided keys are present in an object, etc. |
There was a problem hiding this comment.
Hey @philsturgeon shouldnt that be relative?
| ### CLI | ||
|
|
||
| After installing via one of the methods above, Spectral can be used via your command-line. Take a look at the [CLI docs](./docs/cli.md) for information on the options available. | ||
| For more installation options, see [Getting Started > Installation](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/installation.md) |
There was a problem hiding this comment.
Suggested change
| For more installation options, see [Getting Started > Installation](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/installation.md) | |
| For more installation options, see [Getting Started > Installation](docs/getting-started/installation.md) |
| - [Enabling specific OpenAPI rules](./docs/rulesets.md#enabling-specific-openapi-rules) | ||
| - [Disabling specific OpenAPI rules](./docs/rulesets.md#disabling-specific-openapi-rules) | ||
| - [Changing the severity of a rule](./docs/rulesets.md#changing-the-severity-of-a-rule) | ||
| After [installation](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/installation.md) take a look at our [getting started documentation](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/concepts.md). |
There was a problem hiding this comment.
Suggested change
| After [installation](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/installation.md) take a look at our [getting started documentation](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/concepts.md). | |
| After [installation](docs/getting-started/installation.md) take a look at our [getting started documentation](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/concepts.md). |
| ## Programmatic usage | ||
|
|
||
| Spectral is written in TypeScript (then compiled to JavaScript) and can be used directly for when you need to use Spectral programmatically. Take a look at our ["JavaScript API documentation"](docs/js-api.md). | ||
| - [Adding a rule](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/rulesets.md#adding-a-rule) |
There was a problem hiding this comment.
Suggested change
| - [Adding a rule](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/rulesets.md#adding-a-rule) | |
| - [Adding a rule](docs/getting-started/rulesets.md#adding-a-rule) |
There was a problem hiding this comment.
Seeing as the README is not going to be read by platform these links will not be transformed to docs URLs and we'll be sending our GitHub users to the markdown files here in the repo. This is temporary until we get symlinks supported in Studio, and can symlink the README.md to docs/intro.md.
chris-miaskowski
previously approved these changes
Aug 8, 2019
There was a problem hiding this comment.
Hey @philsturgeon I did another pass. Added one or two suggestions (change URLs from absolute to relative) but not sure if they make sense. If they do then please fix and feel free to merge.
philsturgeon
pushed a commit
that referenced
this pull request
Aug 8, 2019
New documentation covering CLI and JS APIs, rulesets, workflows, core rules, etc.
philsturgeon
pushed a commit
that referenced
this pull request
Aug 8, 2019
* docs: include 2.x/3.x to 4.0 migration guide (#381) * docs: include 2.x/3.x to 4.0 migration guide * cleaned up migration guide * remove periods for consistency * docs: feedback from @philsturgeon * docs: cover recommended property * clearing a few things up * Update 4.0.md * fix typo * Documentation Rewrite (#417) New documentation covering CLI and JS APIs, rulesets, workflows, core rules, etc.
philsturgeon
pushed a commit
that referenced
this pull request
Aug 20, 2019
* docs: include 2.x/3.x to 4.0 migration guide (#381) * docs: include 2.x/3.x to 4.0 migration guide * cleaned up migration guide * remove periods for consistency * docs: feedback from @philsturgeon * docs: cover recommended property * clearing a few things up * Update 4.0.md * fix typo * Documentation Rewrite (#417) New documentation covering CLI and JS APIs, rulesets, workflows, core rules, etc.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixes #302.
Checklist
Does this PR introduce a breaking change?