Skip to content

Commit

Permalink
New lint rules for new doc site (MystenLabs#14608)
Browse files Browse the repository at this point in the history
## Description 
New lint rules for new doc site

## Test Plan 
Failed documentation test when files are modified in the old doc folder:
`doc/tips/xcode-instruments.md`
https://github.com/MystenLabs/sui/actions/runs/6724616879/job/18277279110?pr=14608
![Screenshot 2023-11-01 at 1 15
16 PM](https://github.com/MystenLabs/sui/assets/15659060/fc20ea0a-0817-4090-ae7e-a9413e3ce5e0)
  • Loading branch information
ebmifa authored Nov 1, 2023
1 parent bd34f50 commit 1e0afa6
Show file tree
Hide file tree
Showing 12 changed files with 40 additions and 20 deletions.
10 changes: 8 additions & 2 deletions .github/actions/diffs/action.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,9 @@ outputs:
isDoc:
description: True when changes happened to some documentation
value: "${{ steps.diff.outputs.isDoc }}"
isOldDoc:
description: True when changes happened to old doc folder
value: "${{ steps.diff.outputs.isOldDoc }}"
isRust:
description: True when changes happened to the Rust code
value: "${{ steps.diff.outputs.isRust }}"
Expand Down Expand Up @@ -33,9 +36,12 @@ runs:
- '.github/workflows/rust.yml'
- '.github/workflows/external.yml'
isDoc:
- 'doc/**'
- '*.md'
- 'docs/content/**'
- '*.mdx'
- '.github/workflows/docs.yml'
isOldDoc:
- 'doc/**'
- '*.md'
isMove:
- 'crates/sui-framework/**'
- 'crates/sui-framework-build/**'
Expand Down
22 changes: 18 additions & 4 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,20 +12,34 @@ jobs:
runs-on: [ubuntu-latest]
outputs:
isDoc: ${{ steps.diff.outputs.isDoc }}
isOldDoc: ${{ steps.diff.outputs.isOldDoc }}
steps:
- uses: actions/checkout@7dd9e2a3dc350cf687eb1b2a4fadfee8c8e49675 # pin@v3
- uses: actions/checkout@v3 # pin@v3
- name: Detect Changes
uses: './.github/actions/diffs'
id: diff

spelling:
name: Lint documentation
needs: diff
if: needs.diff.outputs.isDoc == 'true'
runs-on: [ubuntu-latest]

steps:
- uses: actions/checkout@7dd9e2a3dc350cf687eb1b2a4fadfee8c8e49675 # pin@v3
- uses: actions/checkout@v3 # pin@v3
- name: Spell Check Docs
uses: crate-ci/[email protected]
with:
files: ./doc ./*.md
files: ./docs/content

old-doc-folder-notice:
name: Old doc folder notice
needs: diff
if: needs.diff.outputs.isOldDoc == 'true'
runs-on: [ubuntu-latest]

steps:
- name: Output error
run: |
echo "::error::Sui documentation has moved from doc/* to docs/content/* folder. (*.md files are now *.mdx)"
exit 1
2 changes: 1 addition & 1 deletion docs/content/concepts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -36,5 +36,5 @@ Sui is different than other blockchains. The concepts explored in this section p
<Cards>
<Card title="SUI token" href="concepts/tokenomics/sui-token" />
<Card title="Gas in Sui" href="concepts/tokenomics/gas-in-sui" />
<Card title="Stroage fund" href="concepts/tokenomics/storage-fund" />
<Card title="Storage fund" href="concepts/tokenomics/storage-fund" />
</Cards>
Original file line number Diff line number Diff line change
Expand Up @@ -140,7 +140,7 @@ module examples::account {
use sui::dynamic_field as df;
use sui::tx_context::TxContext;

const EBalanceDNE: u64 = 1;
const EBalanceDONE: u64 = 1;

/// Account object that `Coin`s can be sent to. Balances of different types
/// are held as dynamic fields indexed by the `Coin` type's `type_name`.
Expand Down Expand Up @@ -176,7 +176,7 @@ module examples::account {
let account_balance_type = AccountBalance<T>{};
let account_uid = &mut account.id;
// Make sure what we are withdrawing exists
assert!(df::exists_(account_uid, account_balance_type), EBalanceDNE);
assert!(df::exists_(account_uid, account_balance_type), EBalanceDONE);
let balance: &mut Coin<T> = df::borrow_mut(account_uid, account_balance_type);
coin::split(balance, amount, ctx)
}
Expand All @@ -189,4 +189,4 @@ module examples::account {
transfer::transfer(account, to);
}
}
```
```
4 changes: 2 additions & 2 deletions docs/content/concepts/dynamic-fields/versioning.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,7 @@ One distinction dynamic fields have to wrapped objects is that if a transaction

Adding a new dynamic field to a parent object also creates a `Field` object, responsible for associating the field name and value with that parent. Unlike other newly created objects, the ID for the resulting instance of `Field` is not created using `sui::object::new`. Instead, it is computed as a hash of the parent object ID and the type and value of the field name, so that you can use it to look-up the `Field` via its parent and name.

When you remove a field, Sui deletes its associated `Field`, and if you add a new field with the same name, Sui creates a new instance with the same ID. Versioning using Lamport timestamps, coupled with dynamic fields being only accessable through their parent object, ensures that (ID, version) pairs are not reused in the process:
When you remove a field, Sui deletes its associated `Field`, and if you add a new field with the same name, Sui creates a new instance with the same ID. Versioning using Lamport timestamps, coupled with dynamic fields being only accessible through their parent object, ensures that (ID, version) pairs are not reused in the process:

- The transaction that deletes the original field increments the parent's version to be greater than the deleted field's version.
- The transaction that creates the new version of the same field creates the field with a version that is greater than the parent's version.
Expand Down Expand Up @@ -180,4 +180,4 @@ version = "1.0.0"
another_pkg = { git = "https://github.com/another_pkg/another_pkg.git" , version = "2.0.0"}
```

At this point, the version references in the manifest are used only for user-level documentation as the `publish` and `upgrade` commands do not leverage this information. If you publish a package with a certain package version in the manifest file and then modify and re-publish the same package with a different version (using `publish` command rather than `upgrade` command), the two are considered different packages, rather than on-chain versions of the same package. You cannot use any of these packages as a dependency override to stand in for the other one. While you can specify this type of override when building a package, it results in an error when publishing or upgrading on chain.
At this point, the version references in the manifest are used only for user-level documentation as the `publish` and `upgrade` commands do not leverage this information. If you publish a package with a certain package version in the manifest file and then modify and re-publish the same package with a different version (using `publish` command rather than `upgrade` command), the two are considered different packages, rather than on-chain versions of the same package. You cannot use any of these packages as a dependency override to stand in for the other one. While you can specify this type of override when building a package, it results in an error when publishing or upgrading on chain.
2 changes: 1 addition & 1 deletion docs/content/guides/developer/app-examples/coin-flip.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -251,7 +251,7 @@ module satoshi_flip::counter_nft {

This might look familiar from the house module. You set the module name, import functions from the standard library, and initialize the `Counter` object. The `Counter` object has the `key` ability, but does not have `store` - this prevents the object from being transferable.

In addition, you create `mint` and `transfer_to_sender` functions used when the game is set up to create the `Counter` object (with an inital count of `0`) and transfer the object to the sender of the transaction. And finally a `burn` function to allow deletion of the `Counter`.
In addition, you create `mint` and `transfer_to_sender` functions used when the game is set up to create the `Counter` object (with an initial count of `0`) and transfer the object to the sender of the transaction. And finally a `burn` function to allow deletion of the `Counter`.

You have a `Counter` object, as well as functions that initialize and burn the object, but you need a way to increment the counter. Add the following code to the module:

Expand Down
2 changes: 1 addition & 1 deletion docs/content/guides/developer/app-examples/e2e-counter.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -168,7 +168,7 @@ This component renders a button that enables the user to create a counter. Now,

To do this, you need to construct a `TransactionBlock`, with the appropriate `moveCall` transaction, and then sign and execute the programmable transaction block (PTB).

First, import `TransactionBlock` from `@mysten/sui.js`, `COUNTER_PACKAGE_ID` from your constants.ts file created previouly, and `useSignAndExecuteTransactionBlock` from `@mysten/dapp-kit`.
First, import `TransactionBlock` from `@mysten/sui.js`, `COUNTER_PACKAGE_ID` from your constants.ts file created previously, and `useSignAndExecuteTransactionBlock` from `@mysten/dapp-kit`.

```ts
import { useSignAndExecuteTransactionBlock } from "@mysten/dapp-kit";
Expand Down
2 changes: 1 addition & 1 deletion docs/content/guides/developer/first-app/client-tssdk.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Client App with Sui TypeScript SDK
---

This exercise walks you through setting up dApp Kit in a React App, allowing you to connect to wallets, and query data from Sui RPC nodes to display in your app. If you want to get a fully functional app up and running quickly, run the follwoing command in a terminal or console to scaffold a new app with all steps in this exercise already implemented:
This exercise walks you through setting up dApp Kit in a React App, allowing you to connect to wallets, and query data from Sui RPC nodes to display in your app. If you want to get a fully functional app up and running quickly, run the following command in a terminal or console to scaffold a new app with all steps in this exercise already implemented:

{@include: ../../../snippets/info-pnpm-required.mdx}

Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Sui Environment Setup
description: Get the background information you need before you start developing on Sui. Learn the layout of the Sui monorepository and the suggested develoment environment for working with Move.
description: Get the background information you need before you start developing on Sui. Learn the layout of the Sui monorepository and the suggested development environment for working with Move.
---

Before you start developing with Sui and Move, you should familiarize yourself with how to contribute to Sui, how Sui is structured, what tools and SDKs exist, and what plugins are available to use in your IDE.
Expand Down
4 changes: 2 additions & 2 deletions docs/content/guides/operator/archives.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ description: The archive is a historical record of all transactions on Sui. Enab
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

A Sui archive is a history of all transaction data on Sui, trailing behind the latest checkpoint by 10 minutes. As a Sui node operator, you can write this history to an object store like S3, GCS, or similar for safe keeping. Saving this archive data is considered a best practice because Sui prunes transactions on Full nodes to remove historical transactions and their effects. Peer nodes, for example, might not catch up with all transactions and effects through synchronization if they lag behind the current epoch by more than the lastest few epochs. Instead of relying on synchronization, peer nodes can fallback to downloading this information from an archive.
A Sui archive is a history of all transaction data on Sui, trailing behind the latest checkpoint by 10 minutes. As a Sui node operator, you can write this history to an object store like S3, GCS, or similar for safe keeping. Saving this archive data is considered a best practice because Sui prunes transactions on Full nodes to remove historical transactions and their effects. Peer nodes, for example, might not catch up with all transactions and effects through synchronization if they lag behind the current epoch by more than the latest few epochs. Instead of relying on synchronization, peer nodes can fallback to downloading this information from an archive.

Sui Archival nodes (Full nodes that write to an archive) don't store historical state on local storage and don't help query historical data. They serve the purpose of enabling peer nodes to catch up to the latest checkpoint and are useful for auditing and verifying the complete history of all transactions on the network.

Expand Down Expand Up @@ -89,4 +89,4 @@ state-archive-read-config:
```
</TabItem>
</Tabs>
</Tabs>
2 changes: 1 addition & 1 deletion docs/content/references/cli.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ If the command is not found, follow the instructions in [Install Sui](/guides/de

## Update CLI

To get the latest version of the CLI, you can run the following commmand from a terminal or console. Be sure to replace `<BRANCH-NAME>` with `main`, `devnet`, `testnet`, or `mainnet` to get the desired version. For more information on the branches available, see [Sui Environment Setup](/guides/developer/getting-started/sui-environment.mdx).
To get the latest version of the CLI, you can run the following command from a terminal or console. Be sure to replace `<BRANCH-NAME>` with `main`, `devnet`, `testnet`, or `mainnet` to get the desired version. For more information on the branches available, see [Sui Environment Setup](/guides/developer/getting-started/sui-environment.mdx).

```shell
cargo install --locked --git https://github.com/MystenLabs/sui.git --branch <BRANCH-NAME> sui
Expand Down
2 changes: 1 addition & 1 deletion docs/content/standards/deepbook/trade-and-swap.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ When we create a pool in DeepBook, we need to specify the BaseAsset, QuoteAsset,
```rust
/// Parameters expected by this func
///
/// 0. `[registry]` Object ID refers to the pool registery
/// 0. `[registry]` Object ID refers to the pool registry
/// 1. `[tick_size]` Minimal Price Change Accuracy of this pool
/// 2. `[lot_size]` Minimal lot Change Accuracy of this pool
/// 3. `[coin]` Object ID of the sui coin, to pay fee for create pool (100 MIST sui charged)
Expand Down

0 comments on commit 1e0afa6

Please sign in to comment.