[docs] Complete parent topics #16334
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
3 Ignored Deployments
|
github-actions
bot
added
the
Type: Documentation
ronny-mysten
changed the title
There was a problem hiding this comment.
Left some nits/questions but big fan of this change overall and the patterns it's setting up in ours docs, thanks @ronny-mysten !
| @@ -101,3 +101,7 @@ module examples::donuts_with_events { | |||
| } | |||
| } | |||
| ``` | |||
|
|
|||
| ## Related links | |||
|
|
||
| - [Sui GraphQL Reference](../references/sui-graphql.mdx): Auto-generated reference for the Sui GraphQL API. | ||
| - [Migrating to GraphQL](../guides/developer/advanced/graphql-migration.mdx): Migrate from JSON-RPC API to GraphQL. | ||
| - [Querying Sui GraphQL](../guides/developer/getting-started/graphql-rpc.mdx): Get started making queries of Sui GraphQL. |
There was a problem hiding this comment.
nit: We should order this link before the migrating one given that it's the getting started guide.
docs/content/concepts/transfers.mdx
Outdated
|
|
||
| ## Custom Transfer Rules | ||
|
|
||
| On Sui, you can create custom transfer rules for objects that define the transfer conditions that must be met for a valid transfer operation. The object you want to create custom transfer rules for cannot have the `store` ability, as that ability provides unrestricted access to that object without having to go through the module that defines it. |
There was a problem hiding this comment.
nit: overuse of the word "transfer"? Also clarifying what "unrestricted access" means in this case (my amended copy probably needs to have links introduced for references to public_transfer and TransferObjects).
| On Sui, you can create custom transfer rules for objects that define the transfer conditions that must be met for a valid transfer operation. The object you want to create custom transfer rules for cannot have the `store` ability, as that ability provides unrestricted access to that object without having to go through the module that defines it. | |
| On Sui, you can create custom transfer rules for objects that define the conditions that must be met for a valid transfer operation. The object you want to create custom transfer rules for cannot have the `store` ability, as that ability enables unrestricted transfers for the type via `sui::transfer::public_transfer` or the `TransferObjects` transaction command. |
docs/content/references.mdx
Outdated
There was a problem hiding this comment.
Want to say that the "Card" format is really nice and digestable for these landing pages and it would be nice to use it more.
Also for this particular one, we need to re-order the cards to match the sections in the sidebar.
There was a problem hiding this comment.
So the cards are meant to only be used on the Overview pages. The idea of the Overview pages is to offer guidance to people new to Sui (or its docs), not to exactly emulate the navigation. Most people get to their page through search, so the idea is that if you're on an Overview page, you might just need some general guidance of the things deemed most important or most generally accessed for that section (max 3 per section). The initial pages chosen to be a card are just a starting point. The hope is to use traffic data to inform what pages to highlight going forward. Advanced users can drill down the nav tree to get to the exact topic they need (if not by search). Having written all that, those are just the current guidelines. Guidelines can certainly be changed.
docs/content/sidebars/concepts.js
Outdated
| @@ -6,7 +6,7 @@ const concepts = [ | |||
| 'concepts/components', | |||
| { | |||
| type: 'category', | |||
| label: 'Sui GraphQL RPC', | |||
| label: 'Sui GraphQL', | |||
There was a problem hiding this comment.
I think I may have been responsible for putting this so high up in the "Concepts" sidebar, but I kind of regret that decision. Thoughts on moving it lower down, e.g. next to "Sui Architecture"?
There was a problem hiding this comment.
Ha. Moved into App Developers. I wouldn't be against SA, but just thought app devs would be more interested than someone looking into architecture. URL remains the same, so easy to move. Let me know.
There was a problem hiding this comment.
In this case, I meant to keep it as a top-level thing, but put it next to (just above?) "Sui Architecture" rather than nested within it, because there are reasons to use RPC outside of app development, but will leave it with you!
docs/content/sidebars/references.js
Outdated
There was a problem hiding this comment.
I have a couple of standardisation questions here (the answers may have broader implications):
- Should we prepend "Sui" or not? We tend to do that with "GraphQL" although not consistently, and we tend not to do that with "JSON-RPC".
- Should we append "Reference" or not -- in this case it seems strange that we don't do it for the overall header but we do for the sub-headings.
- Do we use the term "API" or "RPC" (or both?). Internally we tend to say RPC, but before I joined Mysten and generally the Web3 space, I would have called this an API.
My personal tastes lean towards this structure:
- Sui RPC
- GraphQL
- JSON-RPC
But mostly I care about consistency (for GraphQL in particular, in other sidebars, I think it stands out as being prepended with "Sui" when other sections aren't, and I'm keen to standardise those as well).
There was a problem hiding this comment.
Great call. Followed the suggested convention. Hopefully got everything but may need some later PRs to catch misses.
|
|
||
| Some applications, however, require constraining the scope of the token to a specific purpose. For example, some applications might need a token that you can only use for a specific service, or that an authorized account can only use, or a token that you can block certain accounts from using. A real-world analogy would be a bank account - regulated, bank-controlled, and compliant with certain rules and policies. | ||
|
|
||
| ## Difference with Coin | ||
|
|
||
| ```mermaid |
There was a problem hiding this comment.
FWIW, I do like the image we had for this a little bit better, but this is OK too (and maybe you can coerce mermaid to produce a more similar output)
There was a problem hiding this comment.
Yeah, I did too. We should use Mermaid whenever possible, though, to make maintenance easier for all. This was as close as I could get it. If we really don't want to use mermaid, we'll need to use something publicly available with source files.
There was a problem hiding this comment.
Thoughts on having a section for tokens in general that contains both "Coin" and "Closed-Loop Token"? cc @damirka
There was a problem hiding this comment.
I think it could work! Both are very much connected.
| @@ -12,18 +12,26 @@ Everything on the Sui blockchain is an object. These topics use code examples to | |||
| - [Create Coins](./sui-101/create-coin.mdx) | |||
| - [Create NFTs](./sui-101/create-nft.mdx) | |||
|
|
|||
| ## Building programmable transaction blocks | |||
| ## Working with programmable transaction blocks | |||
There was a problem hiding this comment.
nit: in some places we capitalize the words in titles, in others we don't.
There was a problem hiding this comment.
The only headings that should be title case are ones that are the exact title of a page. This one's tricky as the page is titled Working with PTBs. Didn't want to use that because the acronym in the ToC on the right might be confusing. But it's defined in the first sentence so using Working with PTBs as the title.
| You can create programmable transaction blocks (PTBs) on Sui to perform multiple commands in a single transaction. The [Building Programmable Transaction Blocks](./sui-101/building-ptb.mdx) topic demonstrates how to build a PTB using the Sui TypeScript SDK. | ||
| You can create programmable transaction blocks (PTBs) on Sui to perform multiple commands in a single transaction. The Working with PTBs topics demonstrate how to build efficient PTBs using the Sui TypeScript SDK. | ||
|
|
||
| Go to [Working with PTBs](./sui-101/working-with-ptbs.mdx). | ||
|
|
||
| ## Using events |
| ::: | ||
|
|
||
| ## Related links |
There was a problem hiding this comment.
| ## Related links | |
| ## Related Links |
There was a problem hiding this comment.
So, even though it looks strange on these pages, this one is sentence case because it's not a title.
| @@ -24,3 +24,9 @@ The [`borrow` module](https://github.com/MystenLabs/sui/blob/main/crates/sui-fra | |||
|
|
|||
| Go to [Simulating References](./simulating-refs.mdx). | |||
|
|
|||
| ## Related links | |||
There was a problem hiding this comment.
| ## Related links | |
| ## Related Links |
| --- | ||
|
|
||
| Operator guides demonstrate how to run Full nodes on Sui, whether as a validator or Full node operator. | ||
| Operator guides demonstrate how to run Full nodes on Sui, whether as a validator or operator of a Full node to support your dApp, as well as how to integrate SUI into an exchange. | ||
|
|
||
| ## Sui Full node operators |
There was a problem hiding this comment.
^ Ditto - capitalization
There was a problem hiding this comment.
This one is also correct as is. The "correct" way to write Full node, is Full node. And because the heading is not the title of a page, it's sentence case. I'm not a fan of its current form, either, for what it's worth.
## Description Completes parent topics and moves graphql reference. Also adds Related links section to certain docs, including graphql topics for better discoverability. ## Test Plan How did you test the new or updated feature? --- If your changes are not user-facing and do not break anything, you can skip the following section. Otherwise, please briefly describe what has changed under the Release Notes section. ### Type of Change (Check all that apply) - [ ] protocol change - [ ] user-visible impact - [ ] breaking change for a client SDKs - [ ] breaking change for FNs (FN binary must upgrade) - [ ] breaking change for validators or node operators (must upgrade binaries) - [ ] breaking change for on-chain data layout - [ ] necessitate either a data wipe or data migration ### Release notes
Description
Completes parent topics and moves graphql reference. Also adds Related links section to certain docs, including graphql topics for better discoverability.
Test Plan
How did you test the new or updated feature?
If your changes are not user-facing and do not break anything, you can skip the following section. Otherwise, please briefly describe what has changed under the Release Notes section.
Type of Change (Check all that apply)
Release notes