Restructure API namespace for Cy13

[BlueWinds]

Matching code PR: cypress-io/cypress#25738

This PR reorganizes the API docs.

• It moves all commands - query, action and otherwise - under a single namespace and into the same folder, making them easy to locate alphabetically in the sidebar.
• I've also added a new table-of-contents page, which groups commands by category - assertions, queries, non-queries, in logical groups with a description of each command, to help users find what they're looking for when they don't know a command name.
• On each page, I've moved the contents of the "Rules" heading up, to be part of the "Syntax" heading - this puts all the rules of execution (arguments, requirements, assertions, and yielded value) in the same place. Everything you need to know to successfully use a command is up top, rather than split half at the top and half at the bottom of each page.
  • I've updated the "requires being chained off of..." section of each command to make it clearer - many commands ignore the subject they're given, but very few must be chained off cy.
  • For the "Assertions" section of each command, I've clarified what is asserted before a command executes and what is asserted after it executes, for commands which do both.
  • Some commands were missing ways in which they could time out; I've added all that I'm aware of.
  • I've standardized the wording of the "Yields" section, improving how it explains the query/non-query divide. For commands which "yield the dom elements they've found", I de-standardized the language, so the "Yields" sections clearly says what elements the command is locating.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated
cypress-documentation	✅ Ready (Inspect)	Visit Preview	💬 Add your feedback	Mar 1, 2023 at 3:37PM (UTC)

[emilyrohrbough]

if this is the case, why does it yield stderr? Users can assert of use that value?

[BlueWinds]

Many commands write to stderr even when successful. curl is one example.

https://askubuntu.com/questions/944788/how-does-curl-print-to-terminal-while-piping

When you are using curl to open an URL, you'll get two output:

The status of the curl itself.
The contents of that URL.

Curl should use a way to show these two separately otherwise processing of the real output (URL's content) would be hard and I'll end up with unnecessary contents (curl's status).

So it uses stderr for its status and stdout for the content.

You wouldn't usually curl with cy.exec, but it's a common pattern in linux commands.

[emilyrohrbough]

above doesn't it say it verify the file contents were successfully written to disk?

[BlueWinds]

writeFile yields null, and makes no implicit assertions about the subject it yields.

In my mind, and implicit assertion isn't "any way a command could fail" - it's "things Cypress already checks about the subject". You never need to write ".should('exist')" about subjects, because Cypress implicitly asserts that they exist. In this case the subject is null, and there are no implicit assertions that you could make explicit about it.

[emilyrohrbough]

Left some comments.

[BlueWinds]

Pushed up a reorganization of the /api namespace, including adding a new table of contents.

I still have more feedback to address, but wanted to push up this much for people to look at.

[emilyrohrbough]

A few things:
1- can we update this PR title to reflect these changes.
2- I initially only looked at the doc preview since this PR has 111 file changes. with the restructuring of commands layout, I couldn't/still can't determine which commands are assertions or query commands when clicking through the list of commands. I didn't really realize the table of contents was trying to tell this story. Can we add a badge on the command pages to quickly highlight this?

[emilyrohrbough]

The on-link slug needs updated to account for this url change. https://github.com/cypress-io/cypress-services/blob/develop/packages/on/data/links.yml#L518

[BlueWinds]

That on-link is pointing to a different sort of event, where developers meet up to discuss things. https://www.cypress.io/events/

The slug here looks to be correct to me?

[emilyrohrbough]

Should this majority of these changes be a separate PR so these changes can go out now vs waiting for the v13 release?

It also would have been nice if this was its own PR to make this review a bit smaller.

[BlueWinds]

I think that it makes sense to roll it out all at once with Cy 13, so that we don't have to create multiple versions of the same changes (eg, create an "assertions" section of the new table of contents, then remove it in another PR on another branch). Reorganizing things piecemeal can result in a disjointed user experience; I'd rather have all the changes living in one branch so we can look at the organization holistically.

[emilyrohrbough]

I would expect events to be its own document / api navigation section. I would not expect to find these under the API section.

[BlueWinds]

I spent some time playing around with the layout of this section, and did a little bit of reorganization.

This based on the fact that I really like the way this looks in the table of contents:

I think it flows very naturally like this.

[emilyrohrbough]

I don't mind how this reads, but I do not believe the section Syntax is the correct heading for these concepts since this is more than the syntax at this time.

[BlueWinds]

Good point. I played around with it a bit and came up with this:

How does this look, moving the most basic syntax up top, under the summary of the command, and making "Usage" the top-level header, and having the correct / incorrect just directly under it without a subheader of their own.

[BlueWinds]

I haven't applied them to every command yet because it'd involve manually moving around each file for a direction I'm not 100% sure on yet.

[BlueWinds]

Applied it to the first three commands: .and(), .as(), and .blur(), so people can see it 'live'. If we like the direction I'll go through and apply it to all commands.

[emilyrohrbough]

I'd expect this to be the second bullet after we say what it yields

[BlueWinds]

So the reason I put the "is a query command" first is that some commands have long yields sections. Eg:

---

I was aiming to always have it in the same place (eg, first or second), and in the cases where we need to spend time explaining what's yielded in more detail, having it second ended up making it feel buried under the other text.

---

I'd be fine breaking the consistency here, having it sometimes below what's actually yielded (you're right it is better in the short case) and sometimes above (I do think it needs to come first in the 'long case'). Thoughts?

[emilyrohrbough]

Suggested change

	to go out.
	- When given an alias algument, `cy.wait()` can time out waiting for the
	response to return.
	to go out or the
	response to return.

[BlueWinds]

I broke this out into two sentences because you can specify different request and response timeouts - it seemed like two different timeout options = two different ways it can time out.

[emilyrohrbough]

Suggested change

	- Before executing, `.uncheck()` will wait for the element to reach an
	- Before executing, `.uncheck()` will wait for the subject to reach an

[BlueWinds]

Why would we use a more generic term here? We know it's an element(s), rather than any generic "subject" (this is also detailed above as one of the 'requirements' of the command).

[BlueWinds]

A few things:
1- can we update this PR title to reflect these changes.

Done.

2- I initially only looked at the doc preview since this PR has 111 file changes. with the restructuring of commands layout, I couldn't/still can't determine which commands are assertions or query commands when clicking through the list of commands. I didn't really realize the table of contents was trying to tell this story. Can we add a badge on the command pages to quickly highlight this?

A badge is possible, I'm just not sure the benefit. When visiting a command page, do you need to tell at a glance if a command is a query or not? I put it in the ### Yields section of each command because that's where I felt it was relevant, when chaining commands together.

[AtofStryker]

closing as this work is unplanned for the v13 release