Improve docs and migrate to separate website

.circleci/config.yml

@@ -152,18 +152,25 @@ jobs:
 
   publish:
     docker:
-      - image: cimg/rust:1.74.0
+      - image: cimg/rust:1.74.0-node
     resource_class: large
     steps:
       - checkout
       - setup_remote_docker:
           version: docker23
+      - add_ssh_keys:
+          # needed for pushing to gh-pages
+          fingerprints:
+            - "SHA256:y2r0YUdeS8k6XSOFmgNs4wcTJFv+PIgkY0Yz+af6NSU"
       - run:
           name: Publish new versions to crates.io
           command: ./scripts/publish_cratesio_new_versions.sh
       - run:
           name: Create tags and push joint image manifests
           command: ./docker/tag_images_and_create_joint_image_manifests.sh
+      - run:
+          name: Publish docs
+          command: ./scripts/publish_docs.sh
 
 # Orchestrate jobs using workflows
 # See: https://circleci.com/docs/configuration-reference/#workflows

.github/CONTRIBUTING.md

@@ -1,6 +1,8 @@
-## Pull requests
+# Contributing
+
+To read about PR expectations, check out the [Pull requests](#pull-requests) section. To learn about setting up the project for development and testing, but also getting a per-feature insight, check out [Development](#development).
 
-These guidelines are intended for external contributors.
+## Pull requests
 
 > :warning: IMPORTANT NOTE :warning:
 >
@@ -10,10 +12,6 @@ These guidelines are intended for external contributors.
 
 It is advised to [create an issue](https://github.com/0xSpaceShard/starknet-devnet-rs/issues/new/choose) before creating a PR. Creating an issue is the best way to reach somebody with repository-specific experience who can provide more info on how a problem/idea can be addressed and if a PR is needed.
 
-### Development Docs
-
-The readme contains a section which may be of use to contributors on [this link](https://github.com/0xSpaceShard/starknet-devnet-rs/?tab=readme-ov-file#development).
-
 ### Checklist
 
 The [PR template](pull_request_template.md) contains a checklist. It is important to go through the checklist to ensure the expected quality standards and to ensure the CI workflow succeeds once it is executed.
@@ -26,3 +24,157 @@ Once a PR is created, somebody from the team will review it. When a reviewer lea
 - a link to the commit which addresses the reviewer's observation (simply pasting the sha-digest is enough)
 
 This is an example of a good author-reviewer correspondence: [link](https://github.com/0xSpaceShard/starknet-devnet-rs/pull/310#discussion_r1457142002).
+
+#### Note to reviewers
+
+This project's CI/CD platform (CircleCI) does not have the option to trigger the workflow on external PRs simply with a click. So once a PR is reviewed and looks like its workflow could pass, it can either be accepted & merged it blindly (which shall trigger the workflow on the target branch), or the following workaround can be used to trigger it:
+
+```
+# https://stackoverflow.com/questions/5884784/how-to-pull-remote-branch-from-somebody-elses-repo
+$ git remote add <CONTRIBUTOR> <CONTRIBUTOR_GIT_FORK_URL>
+$ git fetch <CONTRIBUTOR>
+$ git checkout -b <CONTRIBUTOR>/<BRANCH> <CONTRIBUTOR>/<BRANCH>
+
+$ git remote set-url --push <CONTRIBUTOR> git@github.com:0xSpaceShard/starknet-devnet-rs.git
+$ git push <CONTRIBUTOR> HEAD
+```
+
+## Development
+
+### Installation
+
+Some developer scripts used in this project are written in Python 3, with dependencies specified in `scripts/requirements.txt`. You may want to [install the dependencies in a virtual environment](https://docs.python.org/3/library/venv.html#creating-virtual-environments).
+
+Documentation maintenance requires installing `npm`.
+
+### Visual Studio Code
+
+It is highly recommended to get familiar with [Visual Studio Code Dev Containers](https://code.visualstudio.com/docs/devcontainers/create-dev-container#_dockerfile) and install [rust-analyzer](https://code.visualstudio.com/docs/languages/rust) extension.
+
+### Linter
+
+Run the linter with:
+
+```
+$ ./scripts/clippy_check.sh
+```
+
+### Formatter
+
+Run the formatter with:
+
+```
+$ ./scripts/format.sh
+```
+
+If you encounter an error like
+
+```
+error: toolchain 'nightly-x86_64-unknown-linux-gnu' is not installed
+```
+
+Resolve it with:
+
+```
+$ rustup default nightly
+```
+
+### Unused dependencies
+
+To check for unused dependencies, run:
+
+```
+$ ./scripts/check_unused_deps.sh
+```
+
+If you think this reports a dependency as a false positive (i.e. isn't unused), check [here](https://github.com/bnjbvr/cargo-machete#false-positives).
+
+### Spelling check
+
+To check for spelling errors in the code, run:
+
+```
+$ ./scripts/check_spelling.sh
+```
+
+If you think this reports a false-positive, check [here](https://crates.io/crates/typos-cli#false-positives).
+
+### Pre-commit
+
+To speed up development, you can put the previous steps (and more) in a local script defined at `.git/hooks/pre-commit` to have it run before each commit ([more info](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks)).
+
+### Testing
+
+#### Prerequisites
+
+Some tests require the `anvil` command, so you need to [install Foundry](https://book.getfoundry.sh/getting-started/installation). The `anvil` command might not be usable by tests if you run them using VS Code's `Run Test` button available just above the test case. Either run tests using a shell which has foundry/anvil in `PATH`, or modify the BackgroundAnvil Command to specify `anvil` by its path on your system.
+
+To ensure that integration tests pass, be sure to have run `cargo build --release` or `cargo run --release` prior to testing. This builds the production target used in integration tests, so spawning BackgroundDevnet won't time out.
+
+#### Test execution
+
+Run all tests using all available CPUs with:
+
+```
+$ cargo test
+```
+
+The previous command might cause your testing to die along the way due to memory issues. In that case, limiting the number of jobs helps, but depends on your machine (rule of thumb: N=6):
+
+```
+$ cargo test --jobs <N>
+```
+
+#### Benchmarking
+
+To test if your contribution presents an improvement in execution time, check out the script at `scripts/benchmark/command_stat_test.py`.
+
+##### Cargo Bench execution
+
+To run the criterion benchmarks and generate a performance report:
+
+```
+$ cargo bench
+```
+
+This command will compile the benchmarks and run them using all available CPUs on your machine. Criterion will perform multiple iterations of each benchmark to collect performance data and generate statistical analysis.
+
+Check the report created at `target/criterion/report/index.html`
+
+Criterion is highly configurable and offers various options to customise the benchmarking process. You can find more information about Criterion and its features in the [Criterion documentation](https://bheisler.github.io/criterion.rs/book/index.html).
+
+To measure and benchmark memory it is best to use external tools such as Valgrind, Leaks, etc.
+
+### Updating OpenZeppelin contracts
+
+Tests in devnet require an erc20 contract with the `Mintable` feature, keep in mind that before the compilation process of [cairo-contracts](https://github.com/OpenZeppelin/cairo-contracts/) you need to mark the `Mintable` check box in this [wizard](https://wizard.openzeppelin.com/cairo) and copy this implementation to `/src/presets/erc20.cairo`.
+
+If smart contract constructor logic has changed, Devnet's predeployment logic needs to be changed, e.g. `simulate_constructor` in `crates/starknet-devnet-core/src/account.rs`.
+
+### Updating Starknet
+
+Updating the underlying Starknet is done by updating the `blockifier` dependency. It also requires updating the `STARKNET_VERSION` constant.
+
+### Updating JSON-RPC API
+
+Updating the RPC requires following the specification files in the [starknet-specs repository](https://github.com/starkware-libs/starknet-specs). The spec_reader testing utility requires these files to be copied into the Devnet repository. The `RPC_SPEC_VERSION` constant needs to be updated accordingly.
+
+### Updating documentation
+
+The documentation website content has [its own readme](../website/README.md).
+
+### New Devnet version release
+
+To release a new version, follow these steps:
+
+1. Increment the semver in Cargo.toml of those Devnet crates that have changed. Use `scripts/check_crate_changes.sh` for this. Preferably create a separate PR for the increment, such as [this one](https://github.com/0xSpaceShard/starknet-devnet-rs/pull/398). In your PR, also add a documentation entry for the incoming version by running:
+
+   ```
+   npm run docusaurus docs: version <VERSION>
+   ```
+
+2. The publishing of crates and Docker images is done automatically in CI when merged into the main branch.
+
+3. When the CI workflow is done, create a git tag of the form `vX.Y.Z`, push it and create a GitHub release with notes describing changes since the last release.
+
+4. Attach the [binary artifacts built in CI](https://circleci.com/docs/artifacts/#artifacts-overview) to the release. Use `scripts/fetch_ci_binaries.py` to fetch all artifacts of a CI workflow.

.github/pull_request_template.md

@@ -15,6 +15,6 @@
 - [ ] No spelling errors - `./scripts/check_spelling.sh`
 - [ ] Performed code self-review
 - [ ] Rebased to the latest commit of the target branch (or merged it into my branch)
-- [ ] Updated the docs if needed, including the [TODO section](https://github.com/0xSpaceShard/starknet-devnet-rs/?tab=readme-ov-file#todo-to-reach-feature-parity-with-the-pythonic-devnet)
+- [ ] Updated the docs if needed - `./website/README.md`
 - [ ] Linked the [issues](https://github.com/0xSpaceShard/starknet-devnet-rs/issues) resolvable by this PR - [linking info](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword)
 - [ ] Updated the tests if needed; all passing - [execution info](https://github.com/0xSpaceShard/starknet-devnet-rs/?tab=readme-ov-file#test-execution)