Introduce the Sway reference, a more technical Sway source of documen…

…tation. (FuelLabs#2562) ## Summary More information can be found in FuelLabs#2443 . Notes for PR: - The review is meant to take place using `mdbook` so check out the main `README.md` to see how to run it in the browser - This book is incomplete however there are a lot of pages so the idea is to PR this into the repo soon so that subsequent reviews are smaller - No CI added until the book is ready to replace the current book - Ideally reviews are split between multiple people because there is a lot of content Closes FuelLabs#2443 ## Pages Reviewed @matt-user : Program Types -> Functions, Misc Co-authored-by: Bikem <[email protected]> Co-authored-by: Matt <[email protected]> Co-authored-by: Cameron Carstens <[email protected]> Co-authored-by: bing <[email protected]> Co-authored-by: Mitch Martin <[email protected]> Co-authored-by: Mohammad Fawaz <[email protected]> Co-authored-by: Luiz Felipe Bolsoni Gomes <[email protected]> Co-authored-by: K1-R1 <[email protected]> Co-authored-by: Alex Hansen <[email protected]>
aicove · Dec 8, 2022 · ec90af2 · ec90af2
1 parent b87843c
commit ec90af2
Show file tree

Hide file tree

Showing 418 changed files with 5,461 additions and 92 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -130,11 +130,24 @@ jobs:
         uses: peaceiris/actions-mdbook@v1
         with:
           mdbook-version: "0.4.15"
-      - name: Emit logs to tmp.txt, fail if build logs contain 'ERROR'
+      - name: Emit book logs to tmp.txt, fail if build logs contain 'ERROR'
         run: |
-          MDBOOK_preprocessor__FORC_documenter__STRICT="true" mdbook build docs &> tmp.txt
+          MDBOOK_preprocessor__FORC_documenter__STRICT="true" mdbook build docs/book &> tmp.txt
           if cat tmp.txt | grep 'ERROR'
           then
+            cat tmp.txt
+            rm tmp.txt && exit 1
+          else
+            rm tmp.txt && exit 0
+          fi
+
+      - name: Emit reference logs to tmp.txt, fail if build logs contain 'ERROR'
+        run: |
+          mdbook build docs/reference
+          mdbook build docs/reference &> tmp.txt
+          if cat tmp.txt | grep 'ERROR'
+          then
+            cat tmp.txt
             rm tmp.txt && exit 1
           else
             rm tmp.txt && exit 0

diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml
@@ -40,14 +40,46 @@ jobs:
         with:
           mdbook-version: "0.4.15"
 
-      - run: MDBOOK_preprocessor__FORC_documenter__STRICT="true" mdbook build docs
+      - name: Build Sway book
+        run: MDBOOK_preprocessor__FORC_documenter__STRICT="true" mdbook build docs/book
 
-      - name: Deploy master
+      - name: Build Sway reference
+        run: mdbook build docs/reference
+
+      - name: Deploy master book
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/book/book
+          destination_dir: master/book
+        if: github.ref == 'refs/heads/master'
+
+      - name: Deploy master reference
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/reference/book
+          destination_dir: master/reference
+        if: github.ref == 'refs/heads/master'
+
+      - name: Create master book redirect file
+        run: |
+          mkdir ./tmp
+          cat > ./tmp/index.html <<EOF
+          <!DOCTYPE html>
+          <meta charset="utf-8">
+          <meta http-equiv="refresh" content="0; URL=../master/book">
+          <link rel="canonical" href="../master/book">
+          EOF
+        if: github.ref == 'refs/heads/master'
+
+      - name: Deploy index.html redirect file to master
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs/book
-          destination_dir: master
+          publish_dir: ./tmp
+          destination_dir: ./master
+          keep_files: true
         if: github.ref == 'refs/heads/master'
 
       - name: Get tag
@@ -56,12 +88,40 @@ jobs:
           echo ::set-output name=BRANCH_NAME::${GITHUB_REF#refs/tags/}
         if: startsWith(github.ref, 'refs/tags')
 
-      - name: Deploy tag
+      - name: Deploy book tag
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/book/book
+          destination_dir: ${{ steps.branch_name.outputs.BRANCH_NAME }}/book
+        if: startsWith(github.ref, 'refs/tags')
+
+      - name: Deploy reference tag
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/reference/book
+          destination_dir: ${{ steps.branch_name.outputs.BRANCH_NAME }}/reference
+        if: startsWith(github.ref, 'refs/tags')
+
+      - name: Create tag book redirect file
+        run: |
+          mkdir ./tmp
+          cat > ./tmp/index.html <<EOF
+          <!DOCTYPE html>
+          <meta charset="utf-8">
+          <meta http-equiv="refresh" content="0; URL=../${{ steps.branch_name.outputs.BRANCH_NAME }}/book">
+          <link rel="canonical" href="../${{ steps.branch_name.outputs.BRANCH_NAME }}/book">
+          EOF
+        if: startsWith(github.ref, 'refs/tags')
+
+      - name: Deploy index.html redirect file to tag
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs/book
-          destination_dir: ${{ steps.branch_name.outputs.BRANCH_NAME }}
+          publish_dir: ./tmp
+          destination_dir: ./${{ steps.branch_name.outputs.BRANCH_NAME }}
+          keep_files: true
         if: startsWith(github.ref, 'refs/tags')
 
       - name: Create latest HTML redirect file
@@ -71,8 +131,8 @@ jobs:
           cat > ./latest/index.html <<EOF
           <!DOCTYPE html>
           <meta charset="utf-8">
-          <meta http-equiv="refresh" content="0; URL=../${{ steps.branch_name.outputs.BRANCH_NAME }}/">
-          <link rel="canonical" href="../${{ steps.branch_name.outputs.BRANCH_NAME }}/">
+          <meta http-equiv="refresh" content="0; URL=../${{ steps.branch_name.outputs.BRANCH_NAME }}/book">
+          <link rel="canonical" href="../${{ steps.branch_name.outputs.BRANCH_NAME }}/book">
           EOF
 
       - name: Set latest to point to tag

diff --git a/docs/.gitignore → docs/book/.gitignore b/docs/.gitignore → docs/book/.gitignore
diff --git a/docs/README.md → docs/book/README.md b/docs/README.md → docs/book/README.md
diff --git a/docs/book.toml → docs/book/book.toml b/docs/book.toml → docs/book/book.toml
diff --git a/docs/src/README.md → docs/book/src/README.md b/docs/src/README.md → docs/book/src/README.md
diff --git a/docs/src/SUMMARY.md → docs/book/src/SUMMARY.md b/docs/src/SUMMARY.md → docs/book/src/SUMMARY.md
diff --git a/docs/src/advanced/assembly.md → docs/book/src/advanced/assembly.md b/docs/src/advanced/assembly.md → docs/book/src/advanced/assembly.md
@@ -26,7 +26,7 @@ pub fn add_1(num: u32) -> u32 {
 An `asm` block can only return a single register. If you really need to return more than one value, you can modify a tuple. Here's an example showing how can implement this `(u64, u64)`:
 
 ```sway
-{{#include ../../../examples/asm_return_tuple_pointer/src/main.sw}}
+{{#include ../../../../examples/asm_return_tuple_pointer/src/main.sw}}
 ```
 
 Note that this is contrived example meant to demonstrate the syntax; there's absolutely no need to use assembly to add integers!

diff --git a/docs/src/advanced/generic_types.md → docs/book/src/advanced/generic_types.md b/docs/src/advanced/generic_types.md → docs/book/src/advanced/generic_types.md
diff --git a/docs/src/advanced/index.md → docs/book/src/advanced/index.md b/docs/src/advanced/index.md → docs/book/src/advanced/index.md
diff --git a/docs/src/advanced/traits.md → docs/book/src/advanced/traits.md b/docs/src/advanced/traits.md → docs/book/src/advanced/traits.md
diff --git a/docs/src/basics/blockchain_types.md → docs/book/src/basics/blockchain_types.md b/docs/src/basics/blockchain_types.md → docs/book/src/basics/blockchain_types.md
@@ -51,27 +51,27 @@ The `Identity` type is an enum that allows for the handling of both `Address` an
 An `Identity` is implemented as follows.
 
 ```sway
-{{#include ../../../sway-lib-std/src/identity.sw:docs_identity}}
+{{#include ../../../../sway-lib-std/src/identity.sw:docs_identity}}
 ```
 
 Casting to an `Identity` must be done explicitly:
 
 ```sway
-{{#include ../../../examples/identity/src/main.sw:cast_to_identity}}
+{{#include ../../../../examples/identity/src/main.sw:cast_to_identity}}
 ```
 
 A `match` statement can be used to return to an `Address` or `ContractId` as well as handle cases in which their execution differs.
 
 ```sway
-{{#include ../../../examples/identity/src/main.sw:identity_to_contract_id}}
+{{#include ../../../../examples/identity/src/main.sw:identity_to_contract_id}}
 ```
 
 ```sway
-{{#include ../../../examples/identity/src/main.sw:different_executions}}
+{{#include ../../../../examples/identity/src/main.sw:different_executions}}
 ```
 
 A common use case for `Identity` is for access control. The use of `Identity` uniquely allows both `ContractId` and `Address` to have access control inclusively.
 
 ```sway
-{{#include ../../../examples/identity/src/main.sw:access_control_with_identity}}
+{{#include ../../../../examples/identity/src/main.sw:access_control_with_identity}}
 ```
diff --git a/docs/src/basics/built_in_types.md → docs/book/src/basics/built_in_types.md b/docs/src/basics/built_in_types.md → docs/book/src/basics/built_in_types.md
@@ -114,5 +114,5 @@ x[0] = 0;
 ```
 
 ```sway
-{{#include ../../../examples/arrays/src/main.sw}}
+{{#include ../../../../examples/arrays/src/main.sw}}
 ```
diff --git a/docs/src/basics/comments_and_logging.md → docs/book/src/basics/comments_and_logging.md b/docs/src/basics/comments_and_logging.md → docs/book/src/basics/comments_and_logging.md
diff --git a/docs/src/basics/control_flow.md → docs/book/src/basics/control_flow.md b/docs/src/basics/control_flow.md → docs/book/src/basics/control_flow.md
@@ -35,7 +35,7 @@ Note that all branches of the `if` expression must return a value of the same ty
 Sway supports advanced pattern matching through exhaustive `match` expressions.
 
 ```sway
-{{#include ../../../examples/match_statements/src/main.sw}}
+{{#include ../../../../examples/match_statements/src/main.sw}}
 ```
 
 ## Loops
@@ -57,13 +57,13 @@ You need the `while` keyword, some condition (`value < 10` in this case) which w
 `break` and `continue` keywords are available to use inside the body of a `while` loop. The purpose of the `break` statement is to break out of a loop early:
 
 ```sway
-{{#include ../../../examples/break_and_continue/src/main.sw:break_example}}
+{{#include ../../../../examples/break_and_continue/src/main.sw:break_example}}
 ```
 
 The purpose of the `continue` statement is to skip a portion of a loop in an iteration and jump directly into the next iteration:
 
 ```sway
-{{#include ../../../examples/break_and_continue/src/main.sw:continue_example}}
+{{#include ../../../../examples/break_and_continue/src/main.sw:continue_example}}
 ```
 
 ### Nested loops

diff --git a/docs/src/basics/functions.md → docs/book/src/basics/functions.md b/docs/src/basics/functions.md → docs/book/src/basics/functions.md
@@ -24,13 +24,13 @@ fn main() {
 We can make a function parameter mutable by adding `ref mut` before the parameter name. This allows mutating the argument passed into the function when the function is called. For example:
 
 ```sway
-{{#include ../../../examples/ref_mut_params/src/main.sw:increment}}
+{{#include ../../../../examples/ref_mut_params/src/main.sw:increment}}
 ```
 
 This function is allowed to mutate its parameter `num` because of the `mut` keyword. In addition, the `ref` keyword instructs the function to modify the argument passed to it when the function is called, instead of modifying a local copy of it.
 
 ```sway
-{{#include ../../../examples/ref_mut_params/src/main.sw:call_increment}}
+{{#include ../../../../examples/ref_mut_params/src/main.sw:call_increment}}
 ```
 
 Note that the variable `num` itself has to be declared as mutable for the above to compile.
@@ -41,13 +41,13 @@ Note that the variable `num` itself has to be declared as mutable for the above
 Similarly, `ref mut` can be used with more complex data types such as:
 
 ```sway
-{{#include ../../../examples/ref_mut_params/src/main.sw:tuple_and_enum}}
+{{#include ../../../../examples/ref_mut_params/src/main.sw:tuple_and_enum}}
 ```
 
 We can then call these functions as shown below:
 
 ```sway
-{{#include ../../../examples/ref_mut_params/src/main.sw:call_tuple_and_enum}}
+{{#include ../../../../examples/ref_mut_params/src/main.sw:call_tuple_and_enum}}
 ```
 
 > **Note**

diff --git a/docs/src/basics/index.md → docs/book/src/basics/index.md b/docs/src/basics/index.md → docs/book/src/basics/index.md
diff --git a/...asics/methods_and_associated_functions.md → ...asics/methods_and_associated_functions.md b/...asics/methods_and_associated_functions.md → ...asics/methods_and_associated_functions.md
@@ -40,11 +40,11 @@ To call a method, simply use dot syntax: `foo.iz_baz_true()`.
 Similarly to [free functions](functions.md), methods and associated functions may accept `ref mut` parameters. For example:
 
 ```sway
-{{#include ../../../examples/ref_mut_params/src/main.sw:move_right}}
+{{#include ../../../../examples/ref_mut_params/src/main.sw:move_right}}
 ```
 
 and when called:
 
 ```sway
-{{#include ../../../examples/ref_mut_params/src/main.sw:call_move_right}}
+{{#include ../../../../examples/ref_mut_params/src/main.sw:call_move_right}}
 ```
diff --git a/docs/src/basics/structs_tuples_and_enums.md → ...ok/src/basics/structs_tuples_and_enums.md b/docs/src/basics/structs_tuples_and_enums.md → ...ok/src/basics/structs_tuples_and_enums.md
@@ -7,7 +7,7 @@ Structs in Sway are a named grouping of types. You may also be familiar with str
 Firstly, we declare a struct named `Foo` with two fields. The first field is named `bar` and it accepts values of type `u64`, the second field is named `baz` and it accepts `bool` values.
 
 ```sway
-{{#include ../../../examples/structs/src/data_structures.sw}}
+{{#include ../../../../examples/structs/src/data_structures.sw}}
 ```
 
 In order to instantiate the struct we use _struct instantiation syntax_, which is very similar to the declaration syntax except with expressions in place of types.
@@ -19,7 +19,7 @@ There are three ways to instantiate the struct.
 - Using a shorthand notation via variables that are the same as the field names
 
 ```sway
-{{#include ../../../examples/structs/src/main.sw}}
+{{#include ../../../../examples/structs/src/main.sw}}
 ```
 
 > **Note**
@@ -42,7 +42,7 @@ Tuples are a [basic static-length type](./built_in_types.md#tuple-types) which c
 You can access values directly by using the `.` syntax. Moreover, multiple variables can be extracted from a tuple using the destructuring syntax.
 
 ```sway
-{{#include ../../../examples/tuples/src/main.sw}}
+{{#include ../../../../examples/tuples/src/main.sw}}
 ```
 
 ## Enums
@@ -52,39 +52,39 @@ _Enumerations_, or _enums_, are also known as _sum types_. An enum is a type tha
 Here, we have defined five potential colors. Each enum variant is just the color name. As there is no extra data associated with each variant, we say that each variant is of type `()`, or unit.
 
 ```sway
-{{#include ../../../examples/enums/src/basic_enum.sw}}
+{{#include ../../../../examples/enums/src/basic_enum.sw}}
 ```
 
 ### Enums of Structs
 
 It is also possible to have an enum variant contain extra data. Take a look at this more substantial example, which combines struct declarations with enum variants:
 
 ```sway
-{{#include ../../../examples/enums/src/enum_of_structs.sw}}
+{{#include ../../../../examples/enums/src/enum_of_structs.sw}}
 ```
 
 ### Enums of Enums
 
 It is possible to define enums of enums:
 
 ```sway
-{{#include ../../../examples/enums/src/enum_of_enums.sw}}
+{{#include ../../../../examples/enums/src/enum_of_enums.sw}}
 ```
 
 #### Preferred usage
 
 The preferred way to use enums is to use the individual (not nested) enums directly because they are easy to follow and the lines are short:
 
 ```sway
-{{#include ../../../examples/enums/src/enums_preferred.sw}}
+{{#include ../../../../examples/enums/src/enums_preferred.sw}}
 ```
 
 #### Inadvisable
 
 If you wish to use the nested form of enums via the `Error` enum from the example above, then you can instantiate them into variables using the following syntax:
 
 ```sway
-{{#include ../../../examples/enums/src/enums_avoid.sw}}
+{{#include ../../../../examples/enums/src/enums_avoid.sw}}
 ```
 
 Key points to note:

diff --git a/docs/src/basics/variables.md → docs/book/src/basics/variables.md b/docs/src/basics/variables.md → docs/book/src/basics/variables.md
@@ -49,7 +49,7 @@ If the value declared cannot be assigned to the declared type, there will be an
 It is possible to define and initialize constant variables in the manifest file `Forc.toml` of a Sway project. These constants then become visible and usable in the corresponding Sway program. Such variables are called configuration-time constants and have to be defined in their own section called `[constants]` in the manifest file. The syntax for declaring such constants is as follows:
 
 ```sway
-{{#include ../../../examples/config_time_constants/Forc.toml:constants}}
+{{#include ../../../../examples/config_time_constants/Forc.toml:constants}}
 ```
 
 Notice that each constant requires two fields: a `type` and a `value`.
@@ -60,7 +60,7 @@ Notice that each constant requires two fields: a `type` and a `value`.
 The constants defined above can now be used in a Sway program that uses the manifest file as follows:
 
 ```sway
-{{#include ../../../examples/config_time_constants/src/main.sw}}
+{{#include ../../../../examples/config_time_constants/src/main.sw}}
 ```
 
 > **Note**

diff --git a/.../blockchain-development/access_control.md → .../blockchain-development/access_control.md b/.../blockchain-development/access_control.md → .../blockchain-development/access_control.md
@@ -7,7 +7,7 @@ Smart contracts require the ability to restrict access to and identify certain u
 To deliver an experience akin to the EVM's access control, the `std` library provides a `msg_sender` function, which identifies a unique caller based upon the call and/or transaction input data.
 
 ```sway
-{{#include ../../../examples/msg_sender/src/main.sw}}
+{{#include ../../../../examples/msg_sender/src/main.sw}}
 ```
 
 The `msg_sender` function works as follows:
@@ -23,11 +23,11 @@ Many contracts require some form of ownership for access control. To accomplish
 The following is an example of how to properly set ownership of a contract:
 
 ```sway
-{{#include ../../../examples/ownership/src/main.sw:set_owner_example}}
+{{#include ../../../../examples/ownership/src/main.sw:set_owner_example}}
 ```
 
 The following is an example of how to properly revoke ownership of a contract:
 
 ```sway
-{{#include ../../../examples/ownership/src/main.sw:revoke_owner_example}}
+{{#include ../../../../examples/ownership/src/main.sw:revoke_owner_example}}
 ```
diff --git a/...ockchain-development/calling_contracts.md → ...ockchain-development/calling_contracts.md b/...ockchain-development/calling_contracts.md → ...ockchain-development/calling_contracts.md
@@ -118,13 +118,13 @@ For example, in the following contract the CEI pattern is violated, because an
 external contract call is executed before a storage write.
 
 ```sway
-{{#include ../../../examples/cei_analysis/src/main.sw}}
+{{#include ../../../../examples/cei_analysis/src/main.sw}}
 ```
 
 Here, `other_contract` is defined as follows:
 
 ```sway
-{{#include ../../../examples/cei_analysis/src/other_contract.sw}}
+{{#include ../../../../examples/cei_analysis/src/other_contract.sw}}
 ```
 
 The CEI pattern analyzer issues a warning as follows, pointing to the

diff --git a/...n-development/hashing_and_cryptography.md → ...n-development/hashing_and_cryptography.md b/...n-development/hashing_and_cryptography.md → ...n-development/hashing_and_cryptography.md
@@ -5,13 +5,13 @@ The Sway standard library provides easy access to a selection of cryptographic h
 ## Hashing
 
 ```sway
-{{#include ../../../examples/hashing/src/main.sw}}
+{{#include ../../../../examples/hashing/src/main.sw}}
 ```
 
 ## Signature Recovery
 
 ```sway
-{{#include ../../../examples/signatures/src/main.sw}}
+{{#include ../../../../examples/signatures/src/main.sw}}
 ```
 
 > **Note**: Recovery of EVM addresses is also supported via `std::vm::evm`.
diff --git a/...src/blockchain-development/identifiers.md → ...src/blockchain-development/identifiers.md b/...src/blockchain-development/identifiers.md → ...src/blockchain-development/identifiers.md
diff --git a/docs/src/blockchain-development/index.md → .../book/src/blockchain-development/index.md b/docs/src/blockchain-development/index.md → .../book/src/blockchain-development/index.md
-Original file line number
+Diff line change
@@ Expand Up / @@ -114,5 +114,5 @@ x[0] = 0; @@
     ```
     ```sway
-    {{#include ../../../examples/arrays/src/main.sw}}
+    {{#include ../../../../examples/arrays/src/main.sw}}
     ```