Script to generate docs for forc commands + examples (FuelLabs#1047)

* Update book with forc commands

* Fix SUMMARY.md errors when merging

* Move all command pages under /commands dir

* Fix broken link to commands/index.md

Co-authored-by: John Adler <[email protected]>

* Prelim version of a script

* Generation of all command pages based on forc --help

* Clean up main.rs

* Re-generate docs with script

* Fix test_format_option_line test

* Re-build docs without comma after options

* Remove extra printlns

* Add logic to insert examples

* Re-generate docs with examples

* generate forc_deploy.md

* Rename command to write-docs

* Fix dependencies ordering within Cargo.toml

* Move more constants

* added dry-run for checking

* Fix clippy checks

* Rework some error handling when doing dry run

* Integrate mdbook build and forc-documenter checks into ci

* Test a hack for checking errors in mdbook

* Add uses checkout

* Fix dashes

* Fix uses/run in single step

* Try if grep

* fix yaml syntax

* fix yaml syntax, for real

* Fix running forc-documenter from project root

* Try cat for github action

* Fix Cargo.lock

* add install forc to forc-documenter job

* Missed out args line

* Trim newline from start and end of md files

* Fix index header duplicate and add trim() to result

* Fix dry-run behaviour for index

* Remove all commands before starting write-docs to remove outdated commands

* Re-generate

* Remove outdated forc commands from SUMMARY.md

* Extract code from main.rs into helpers.rs

* Handle updating SUMMARY.md as well

* Fix cargo clippy stuff

* Add readme for forc-documenter

* Add version message

* Re-generate docs

* Re-generate docs

* Revert unintended formatting changes

* Fix typo in forc-documenter README.md

* Rename _command to command

* Refactor code within script

* Separate check functions from helpers module

* More refactoring into components

* Re-arrange functions in main

* Add hello world test as a code block instead of a link

* Add docs for forc plugins

Co-authored-by: John Adler <[email protected]>

.github/workflows/ci.yml

@@ -78,6 +78,25 @@ jobs:
           command: run
           args: --bin build-all-examples
 
+  build-mdbook:
+    needs: cancel-previous-runs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Run mdbook build
+        uses: peaceiris/actions-mdbook@v1
+        with:
+          mdbook-version: '0.4.7'
+      - name: Emit logs to tmp.txt, fail if build logs contain 'ERROR'
+        run: |
+          mdbook build docs &> tmp.txt
+          if cat tmp.txt | grep 'ERROR'
+          then
+            rm tmp.txt && exit 1
+          else
+            rm tmp.txt && exit 0
+          fi
+
   cargo-build-workspace:
     needs: cancel-previous-runs
     runs-on: ubuntu-latest
@@ -206,6 +225,27 @@ jobs:
         with:
           command: test
 
+  forc-documenter-dry-run:
+    needs: cancel-previous-runs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: stable
+      - uses: Swatinem/rust-cache@v1
+      - name: Install Forc
+        uses: actions-rs/cargo@v1
+        with:
+          command: install
+          args: --debug --path ./forc
+      - name: Run forc-documenter in dry run mode
+        uses: actions-rs/cargo@v1
+        with:
+          command: run
+          args: --bin forc-documenter write-docs --dry-run
+
   cargo-unused-deps-check:
     needs: cancel-previous-runs
     runs-on: ubuntu-latest

Cargo.toml

@@ -18,6 +18,7 @@ members = [
     "sway-utils",
     "test",
     "test-sig-gen-util",
+    "scripts/forc-documenter"
 ]
 exclude = [
     "examples/fizzbuzz",

docs/src/SUMMARY.md

@@ -32,6 +32,20 @@
   - [Identifiers](./blockchain-development/identifiers.md)
   - [Native Assets](./blockchain-development/native_assets.md)
   - [Calling Contracts](./blockchain-development/calling_contracts.md)
+- [Forc](./forc/index.md)
+  - [Commands](./forc/commands/index.md)
+    - [forc addr2line](./forc/commands/forc_addr2line.md)
+    - [forc build](./forc/commands/forc_build.md)
+    - [forc clean](./forc/commands/forc_clean.md)
+    - [forc completions](./forc/commands/forc_completions.md)
+    - [forc deploy](./forc/commands/forc_deploy.md)
+    - [forc init](./forc/commands/forc_init.md)
+    - [forc json-abi](./forc/commands/forc_json-abi.md)
+    - [forc parse-bytecode](./forc/commands/forc_parse-bytecode.md)
+    - [forc plugins](./forc/commands/forc_plugins.md)
+    - [forc run](./forc/commands/forc_run.md)
+    - [forc test](./forc/commands/forc_test.md)
+    - [forc update](./forc/commands/forc_update.md)
 - [Testing](./testing/index.md)
   - [Testing with Rust](./testing/testing-with-rust.md)
 - [Advanced Concepts](./advanced/index.md)

docs/src/forc/commands/forc_addr2line.md

@@ -0,0 +1,29 @@
+# forc-addr2line
+Show location and context of an opcode address in its source file
+
+
+## USAGE:
+forc addr2line [OPTIONS] --sourcemap-path <SOURCEMAP_PATH> --opcode-index <OPCODE_INDEX>
+
+
+## OPTIONS:
+
+`-c`, `--context` <_CONTEXT_>
+
+How many lines of context to show [default: 2]
+
+`-g`, `--sourcemap-path` <_SOURCEMAP_PATH_>
+
+Source file mapping in JSON format
+
+`-h`, `--help` 
+
+Print help information
+
+`-i`, `--opcode-index` <_OPCODE_INDEX_>
+
+Opcode index
+
+`-s`, `--search-dir` <_SEARCH_DIR_>
+
+Where to search for the project root [default: .]

docs/src/forc/commands/forc_build.md

@@ -0,0 +1,104 @@
+# forc-build
+Compile the current or target project.
+
+The output produced will depend on the project's program type. Building script, predicate and
+contract projects will produce their bytecode in binary format `<project-name>.bin`. Building
+contracts and libraries will also produce the public ABI in JSON format `<project-name>-abi.json`.
+
+
+## USAGE:
+forc build [OPTIONS]
+
+
+## OPTIONS:
+
+`-g`, `--debug-outfile` <_DEBUG_OUTFILE_>
+
+
+If set, outputs source file mapping in JSON format
+
+
+`-h`, `--help` 
+
+
+Print help information
+
+
+`--minify-json-abi` 
+
+
+By default the JSON for ABIs is formatted for human readability. By using this option
+JSON output will be "minified", i.e. all on one line without whitespace
+
+
+`-o` <_BINARY_OUTFILE_>
+
+
+If set, outputs a binary file representing the script bytes
+
+
+`--offline` 
+
+
+Offline mode, prevents Forc from using the network when managing dependencies. Meaning
+it will only try to use previously downloaded dependencies
+
+
+`--output-directory` <_OUTPUT_DIRECTORY_>
+
+
+The directory in which the sway compiler output artifacts are placed.
+
+By default, this is `<project-root>/out`.
+
+
+`-p`, `--path` <_PATH_>
+
+
+Path to the project, if not specified, current working directory will be used
+
+
+`--print-finalized-asm` 
+
+
+Whether to compile to bytecode (false) or to print out the generated ASM (true)
+
+
+`--print-intermediate-asm` 
+
+
+Whether to compile to bytecode (false) or to print out the generated ASM (true)
+
+
+`--print-ir` 
+
+
+Whether to compile to bytecode (false) or to print out the generated IR (true)
+
+
+`-s`, `--silent` 
+
+
+Silent mode. Don't output any warnings or errors to the command line
+
+
+`--use-orig-asm` 
+
+
+Whether to compile using the original (pre- IR) pipeline
+
+## EXAMPLES:
+
+Compile the sway files of the current project.
+
+```console
+$ forc build
+Compiled script "my-fuel-project".
+Bytecode size is 28 bytes.
+```
+
+The output produced will depend on the project's program type. Building script, predicate and contract projects will produce their bytecode in binary format `<project-name>.bin`. Building contracts and libraries will also produce the public ABI in JSON format `<project-name>-abi.json`.
+
+By default, these artifacts are placed in the `out/` directory.
+
+If a `Forc.lock` file did not yet exist, it will be created in order to pin each of the dependencies listed in `Forc.toml` to a specific commit or version.

docs/src/forc/commands/forc_clean.md

@@ -0,0 +1,19 @@
+# forc-clean
+Removes the default forc compiler output artifact directory, i.e. `<project-name>/out`. Also calls
+`cargo clean` which removes the `target` directory generated by `cargo` when running tests
+
+
+## USAGE:
+forc clean [OPTIONS]
+
+
+## OPTIONS:
+
+`-h`, `--help` 
+
+Print help information
+
+`-p`, `--path` <_PATH_>
+
+Path to the project, if not specified, current working directory will be
+used

docs/src/forc/commands/forc_completions.md

@@ -0,0 +1,125 @@
+# forc-completions
+Generate tab-completion scripts for your shell
+
+
+## USAGE:
+forc completions --shell <SHELL>
+
+
+## OPTIONS:
+
+`-h`, `--help` 
+
+Print help information
+
+`-s`, `--shell` <_SHELL_>
+
+[possible values: zsh, bash, fish, powershell, elvish]
+
+
+DISCUSSION:
+Enable tab completion for Bash, Fish, Zsh, or PowerShell
+The script is output on `stdout`, allowing one to re-direct the
+output to the file of their choosing. Where you place the file
+will depend on which shell, and which operating system you are
+using. Your particular configuration may also determine where
+these scripts need to be placed.
+
+Here are some common set ups for the three supported shells under
+Unix and similar operating systems (such as GNU/Linux).
+
+BASH:
+
+Completion files are commonly stored in `/etc/bash_completion.d/` for
+system-wide commands, but can be stored in
+`~/.local/share/bash-completion/completions` for user-specific commands.
+Run the command:
+
+$ mkdir -p ~/.local/share/bash-completion/completions
+$ forc completions --shell=bash >> ~/.local/share/bash-completion/completions/forc
+
+This installs the completion script. You may have to log out and
+log back in to your shell session for the changes to take effect.
+
+BASH (macOS/Homebrew):
+
+Homebrew stores bash completion files within the Homebrew directory.
+With the `bash-completion` brew formula installed, run the command:
+
+$ mkdir -p $(brew --prefix)/etc/bash_completion.d
+$ forc completions --shell=bash > $(brew --prefix)/etc/bash_completion.d/forc.bash-
+completion
+
+FISH:
+
+Fish completion files are commonly stored in
+`$HOME/.config/fish/completions`. Run the command:
+
+$ mkdir -p ~/.config/fish/completions
+$ forc completions --shell=fish > ~/.config/fish/completions/forc.fish
+
+This installs the completion script. You may have to log out and
+log back in to your shell session for the changes to take effect.
+
+ZSH:
+
+ZSH completions are commonly stored in any directory listed in
+your `$fpath` variable. To use these completions, you must either
+add the generated script to one of those directories, or add your
+own to this list.
+
+Adding a custom directory is often the safest bet if you are
+unsure of which directory to use. First create the directory; for
+this example we'll create a hidden directory inside our `$HOME`
+directory:
+
+$ mkdir ~/.zfunc
+
+Then add the following lines to your `.zshrc` just before
+`compinit`:
+
+fpath+=~/.zfunc
+
+Now you can install the completions script using the following
+command:
+
+$ forc completions --shell=zsh > ~/.zfunc/_forc
+
+You must then either log out and log back in, or simply run
+
+$ exec zsh
+
+for the new completions to take effect.
+
+CUSTOM LOCATIONS:
+
+Alternatively, you could save these files to the place of your
+choosing, such as a custom directory inside your $HOME. Doing so
+will require you to add the proper directives, such as `source`ing
+inside your login script. Consult your shells documentation for
+how to add such directives.
+
+POWERSHELL:
+
+The powershell completion scripts require PowerShell v5.0+ (which
+comes with Windows 10, but can be downloaded separately for windows 7
+or 8.1).
+
+First, check if a profile has already been set
+
+PS C:\> Test-Path $profile
+
+If the above command returns `False` run the following
+
+PS C:\> New-Item -path $profile -type file -force
+
+Now open the file provided by `$profile` (if you used the
+`New-Item` command it will be
+`${env:USERPROFILE}\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1`
+
+Next, we either save the completions file into our profile, or
+into a separate file and source it inside our profile. To save the
+completions into our profile simply use
+
+PS C:\> forc completions --shell=powershell >>
+${env:USERPROFILE}\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1