## Description
Generates the documentation for dependencies & small improvements to the
API.
These changes **DO NOT** create links between dependency docs and the main docs, but generates the dependency docs and ensures there are no conflicts when generating these docs.
What's new so far:
- [x] Programs get their own folders, just like `cargo doc`
- [x] Generates documentation for dependencies by default: Closes#4533
- [x] Fixes possible conflict with `assets` folder: Closes#4545
- [x] Removes old docs before generating new ones: Closes#4544
## Checklist
- [x] I have linked to any relevant issues.
- [x] I have commented my code, particularly in hard-to-understand
areas.
- [x] I have updated the documentation where relevant (API docs, the
reference, and the Sway book).
- [ ] I have added tests that prove my fix is effective or that my
feature works.
- [x] I have added (or requested a maintainer to add) the necessary
`Breaking*` or `New Feature` labels where relevant.
- [x] I have done my best to ensure that my PR adheres to [the Fuel Labs
Code Review
Standards](https://github.com/FuelLabs/rfcs/blob/master/text/code-standards/external-contributors.md).
- [x] I have requested a review from the relevant team or maintainers.
---------
Co-authored-by: Chris O'Brien <eureka@noctua.attlocal.net>
## Description
fixes#4424closes#4424
## Checklist
- [ ] I have linked to any relevant issues.
- [ ] I have commented my code, particularly in hard-to-understand
areas.
- [ ] I have updated the documentation where relevant (API docs, the
reference, and the Sway book).
- [ ] I have added tests that prove my fix is effective or that my
feature works.
- [ ] I have added (or requested a maintainer to add) the necessary
`Breaking*` or `New Feature` labels where relevant.
- [ ] I have done my best to ensure that my PR adheres to [the Fuel Labs
Code Review
Standards](https://github.com/FuelLabs/rfcs/blob/master/text/code-standards/external-contributors.md).
- [ ] I have requested a review from the relevant team or maintainers.
---------
Co-authored-by: Joshua Batty <joshpbatty@gmail.com>
## Description
resolves#2740closes#4157
> In order to give a better highlighting I picked the "meta" scope as
seen in [highlight.js
docs](https://highlightjs.readthedocs.io/en/latest/css-classes-reference.html)
>
> The ["Mode"
](https://highlightjs.readthedocs.io/en/latest/language-guide.html) I've
added provides the html class: _hljs-meta_ however, the result is a
white color for annotation (like plain text) and not a blue color as
requested in the issue.
>
> The solution I've found for this is to add an additional css file to
specify custom behavior for the desired class. I haven't added this file
because I think it's out of scope.
## Checklist
- [✅ ] I have linked to any relevant issues.
- [ ?] I have commented my code, particularly in hard-to-understand
areas.
- [ ?] I have updated the documentation where relevant (API docs, the
reference, and the Sway book).
- [ ?] I have added tests that prove my fix is effective or that my
feature works.
- [✅] I have added (or requested a maintainer to add) the necessary
`Breaking*` or `New Feature` labels where relevant.
- [✅ ] I have done my best to ensure that my PR adheres to [the Fuel
Labs Code Review
Standards](https://github.com/FuelLabs/rfcs/blob/master/text/code-standards/external-contributors.md).
- [ ?] I have requested a review from the relevant team or maintainers.
Co-authored-by: Mohammad Fawaz <mohammadfawaz89@gmail.com>
## Description
Applies the ayu theme to `<pre>` wrapped code blocks using the
`highlight.js` file used in the markdown books.
## Checklist
- [x] I have linked to any relevant issues. Closes#4175
- [x] I have commented my code, particularly in hard-to-understand
areas.
- [x] I have updated the documentation where relevant (API docs, the
reference, and the Sway book).
- [x] I have added tests that prove my fix is effective or that my
feature works.
- [x] I have added (or requested a maintainer to add) the necessary
`Breaking*` or `New Feature` labels where relevant.
- [x] I have done my best to ensure that my PR adheres to [the Fuel Labs
Code Review
Standards](https://github.com/FuelLabs/rfcs/blob/master/text/code-standards/external-contributors.md).
- [x] I have requested a review from the relevant team or maintainers.
Co-authored-by: Joshua Batty <joshpbatty@gmail.com>
## Description
This moves the examples workspace manifest introduced in #4118 into the
`examples/` directory and cleans it up a bit.
We also now integrate the examples workspace into CI, making the old
`examples-checker` script redundant. This old script is also removed as
a part of this PR.
## Checklist
- [x] I have linked to any relevant issues.
- [x] I have commented my code, particularly in hard-to-understand
areas.
- [x] I have updated the documentation where relevant (API docs, the
reference, and the Sway book).
- [x] I have added tests that prove my fix is effective or that my
feature works.
- [x] I have added (or requested a maintainer to add) the necessary
`Breaking*` or `New Feature` labels where relevant.
- [x] I have done my best to ensure that my PR adheres to [the Fuel Labs
Code Review
Standards](https://github.com/FuelLabs/rfcs/blob/master/text/code-standards/external-contributors.md).
- [x] I have requested a review from the relevant team or maintainers.
So far I'm addressing all Clippy warnings except for `result_large_err`:
Example:
```console
warning: the `Err`-variant returned from this function is very large
--> sway-core/src/semantic_analysis/namespace/items.rs:130:56
|
130 | pub(crate) fn check_symbol(&self, name: &Ident) -> Result<&ty::TyDeclaration, CompileError> {
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the `Err`-variant is at least 224 bytes
```
Addressing this seems like it will take some time. Might have to throw
in `Box` in various places. To unblock everyone from working, I'm
allowing `clippy::result_large_err` in CI for now.
This PR is a WIP that aims to address the first 3 steps in #1833.
This is in anticipation of using `forc test` to support unit testing
(rather than Rust integration testing) #1832.
The `forc test` command remains for now, but outputs a message
explaining that the command is now reserved for unit testing and links
to the issues above.
## TODO
- [x] Create a new `sway-test-rs` repo or similar that can be used as a
`cargo generate` template.
- [x] Update Rust integration testing docs in the Sway book to describe
how to use the `cargo generate` command to easily add Sway integration
testing to an existing Rust project.
## Follow-up
- Create a `forc-test-rs` crate that re-exports and extends `fuels` with
useful `forc` functionality for integration testing (e.g. re-exporting
`forc_pkg::build` to ensure sway code is built and available under
`out/` at the start of testing).
Add some missing keywords to the `sway.js` file. This was triggered by
@Braqzen noticing some inconsistent highlighting in the generated MD
books.
Doesn't address custom types not being highlighted but that can be for a
future PR.
* Copy over changes from PR#1669
* Rework `forc new` in terms of `forc init`
This removes all of the duplicated logic from the `forc new` command in
favour of re-using the `forc init` op.
* Add missing doc
* Add missing comment
Co-authored-by: Rashad Alston <rashad@Rashads-MacBook-Pro.local>
Co-authored-by: mitchmindtree <mitchell.nordine@fuel.sh>
Co-authored-by: Rashad Alston <rashad@Rashads-MBP.attlocal.net>
* Add instructions to update mdbook-forc-documenter if 'Commands' or 'Plugins' chapter names change
* replace forc gm example with forc explore, and add 'or plugin' after every reference to command
* Add instructions to add plugin installation within CI
* newline
* more info on taking action
* consistent wording
* Clearer wording on removing plugin
* fix: behaviour -> behavior
* Use permalinks
* use permalink in docs/README.d as well
* forc template resolves the HEAD and fetches the repo. Prints the requested directorie's path
* forc template works with and without template name
* forc init --template removed, pkg.rs unused pub modifier removed
* extra info added before copy, cargo-toml-lint, udeps fix, mdbook fix
* invoke CI
* Update scripts/mdbook-forc-documenter/examples/forc_template.md
Co-authored-by: John Adler <adlerjohn@users.noreply.github.com>
* Update scripts/mdbook-forc-documenter/examples/forc_template.md
Co-authored-by: John Adler <adlerjohn@users.noreply.github.com>
* default url provided, project_name is last parameter to pass without --project_name
* cargo fmt
* println to tracing::info
* local_repo_name to template_name
Co-authored-by: John Adler <adlerjohn@users.noreply.github.com>
* Refactoring to get ready for plugin documentation integration
* Check for errors when updating doucmentation
* Fix formatting of error text
* Remove unused BorrowMut
* Add plugin docs
* strip whitespace to remove version no. from plugin command header
* Better naming for commands/plugins within preprocessor
* extract inject_content
* handle parsing subcommand
* Refactor
* Install plugins within ci and gh-pages
* order plugins alphabetically
* official_plugin_commands -> plugin_commands, since they mean the same
* Handle error messages better
* subcommand_is_parsed -> has_parsed_subcommand_header for consistency
* More consistent expect message
* Add additional white spaces for test_format_subcommand_line
* cargo install --debug to speed things up
* Update input from &Vec<String> to &[String]
* Move forc-explore, forc-fmt, forc-lsp, into forc-plugins dir
* Update CI ymls with new plugins path
* Update all references to forc plugins in ci
* Programatically get plugins from forc-plugins
* Update ci.yml
* Properly install plugins
* Re-add removed cancel-previous-run
* Remove unused actions-rs/cargo
* Update plugins installation for gh-pages.yml
* Improve plugins.rs
* Improved find_forc_plugins_dir
* Remove return line within format_header_line
* Fix bug where preprocessor would panic if not in Sway root (#1618)
While testing, I noticed that the build would panic if you attempted to
`mdbook build` the book while in the `docs` directory. I then realised
we had a misuse of the `current_dir` function which must have slipped
through in a previous PR review. I've fixed this by adding a
`find_sway_repo_root` fn and implementing functions to find the plugins
and examples directories in terms of it.
Co-authored-by: mitchmindtree <mitchell.nordine@fuel.sh>
* Accumulate errors instead of returning
* Update run write-docs message
* Better printing
* Handle index.md and summary.md reporting
* Fix passing in wrong contents into check_index_diff
* Remove RUN_WRITE_DOCS_MESSAGE entirely since it's only used in one place now
* Re-add println Done at the end of script
* Better error message
* Use bail!
* use bail!, again
* Add indentation for code block within forc deploy
* Separate examples from constants
* Update examples.rs to the latest version
* Remove long-form discussion in forc completions help
* Update examples and docs
* Revert examples check to shorten diff forn ow
* Newline
* Newline for docs
* Better formatting
* Add link to book within help
* Update docs
* Remove redundant shell command prefixes $ and PS
* Missed the C:s
* Run write-docs script
* Re-add FORC_COMPLETIONS_EXAMPLE
* Move build-all-examples to scripts
* Remove print
* Reorder scripts/build-all-examples alphabetically
* use clap for build-all-examples
* Cargo.lock update
* Take paths for build-all-examples
* Remove unused import
* Rename build-all-examples -> build-examples
* Update ci.yml with new build-examples command
* Update Cargo.lock
* Add help text for build-examples script
* Use --all and --paths args to differentiate between building all and specific paths
* build-examples --all -> --all-examples to make it even more explicit
* Better description for script
* Refactor script
* Rename build-examples to examples-checker
* update Cargo.toml and Cargo.lock with new script name
* Update CI workflow
* Better usage of Path
* Remove redundant builds, add dedicated fmt job
* Remove usage of success bool in run_forc_command
* Use [] instead of &Vec<>
* handle print_summary failure as error instead of exit(1)
Co-authored-by: bing <binggh@proton.me>
* 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 <adlerjohn@users.noreply.github.com>
* 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 <adlerjohn@users.noreply.github.com>
