Write generated READMEs

.changeset/funny-lamps-relax.md

@@ -0,0 +1,5 @@
+---
+"create-solana-program": patch
+---
+
+Write generated READMEs

template/base/README.md.njk

@@ -1,6 +1,34 @@
 # {{ programName | titleCase }}
 
-TODO
+{# TODO: Uncomment when CI is generated. #}
+{# <a href="https://github.com/{{ organizationName }}/{{ programName }}/actions/workflows/main.yml"><img src="https://img.shields.io/github/actions/workflow/status/{{ organizationName }}/{{ programName }}/main.yml?logo=GitHub" /></a> #}
+<a href="https://explorer.solana.com/address/{{ programAddress }}"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2F{{ organizationName }}%2F{{ programName }}%2Fmain%2Fprogram%2Fidl.json&query=%24.version&label=program%20version&logo=data:image/svg%2bxml;base64,PHN2ZyB3aWR0aD0iMzEzIiBoZWlnaHQ9IjI4MSIgdmlld0JveD0iMCAwIDMxMyAyODEiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CjxnIGNsaXAtcGF0aD0idXJsKCNjbGlwMF80NzZfMjQzMCkiPgo8cGF0aCBkPSJNMzExLjMxOCAyMjEuMDU3TDI1OS42NiAyNzYuNTU4QzI1OC41MzcgMjc3Ljc2NCAyNTcuMTc4IDI3OC43MjUgMjU1LjY2OSAyNzkuMzgyQzI1NC4xNTkgMjgwLjAzOSAyNTIuNTMgMjgwLjM3OCAyNTAuODg0IDI4MC4zNzdINS45OTcxOUM0LjgyODcgMjgwLjM3NyAzLjY4NTY4IDI4MC4wMzUgMi43MDg1NSAyNzkuMzkzQzEuNzMxNDMgMjc4Ljc1MSAwLjk2Mjc3MSAyNzcuODM3IDAuNDk3MDIgMjc2Ljc2NEMwLjAzMTI2OTEgMjc1LjY5IC0wLjExMTI4NiAyNzQuNTA0IDAuMDg2ODcxMiAyNzMuMzVDMC4yODUwMjggMjcyLjE5NiAwLjgxNTI2NSAyNzEuMTI2IDEuNjEyNDMgMjcwLjI3TDUzLjMwOTkgMjE0Ljc2OUM1NC40Mjk5IDIxMy41NjYgNTUuNzg0MyAyMTIuNjA3IDU3LjI4OTMgMjExLjk1QzU4Ljc5NDMgMjExLjI5MyA2MC40MTc4IDIxMC45NTMgNjIuMDU5NSAyMTAuOTVIMzA2LjkzM0MzMDguMTAxIDIxMC45NSAzMDkuMjQ0IDIxMS4yOTIgMzEwLjIyMSAyMTEuOTM0QzMxMS4xOTkgMjEyLjU3NiAzMTEuOTY3IDIxMy40OSAzMTIuNDMzIDIxNC41NjRDMzEyLjg5OSAyMTUuNjM3IDMxMy4wNDEgMjE2LjgyNCAzMTIuODQzIDIxNy45NzdDMzEyLjY0NSAyMTkuMTMxIDMxMi4xMTUgMjIwLjIwMSAzMTEuMzE4IDIyMS4wNTdaTTI1OS42NiAxMDkuMjk0QzI1OC41MzcgMTA4LjA4OCAyNTcuMTc4IDEwNy4xMjcgMjU1LjY2OSAxMDYuNDdDMjU0LjE1OSAxMDUuODEzIDI1Mi41MyAxMDUuNDc0IDI1MC44ODQgMTA1LjQ3NUg1Ljk5NzE5QzQuODI4NyAxMDUuNDc1IDMuNjg1NjggMTA1LjgxNyAyLjcwODU1IDEwNi40NTlDMS43MzE0MyAxMDcuMTAxIDAuOTYyNzcxIDEwOC4wMTUgMC40OTcwMiAxMDkuMDg4QzAuMDMxMjY5MSAxMTAuMTYyIC0wLjExMTI4NiAxMTEuMzQ4IDAuMDg2ODcxMiAxMTIuNTAyQzAuMjg1MDI4IDExMy42NTYgMC44MTUyNjUgMTE0LjcyNiAxLjYxMjQzIDExNS41ODJMNTMuMzA5OSAxNzEuMDgzQzU0LjQyOTkgMTcyLjI4NiA1NS43ODQzIDE3My4yNDUgNTcuMjg5MyAxNzMuOTAyQzU4Ljc5NDMgMTc0LjU1OSA2MC40MTc4IDE3NC44OTkgNjIuMDU5NSAxNzQuOTAySDMwNi45MzNDMzA4LjEwMSAxNzQuOTAyIDMwOS4yNDQgMTc0LjU2IDMxMC4yMjEgMTczLjkxOEMzMTEuMTk5IDE3My4yNzYgMzExLjk2NyAxNzIuMzYyIDMxMi40MzMgMTcxLjI4OEMzMTIuODk5IDE3MC4yMTUgMzEzLjA0MSAxNjkuMDI4IDMxMi44NDMgMTY3Ljg3NUMzMTIuNjQ1IDE2Ni43MjEgMzEyLjExNSAxNjUuNjUxIDMxMS4zMTggMTY0Ljc5NUwyNTkuNjYgMTA5LjI5NFpNNS45OTcxOSA2OS40MjY3SDI1MC44ODRDMjUyLjUzIDY5LjQyNzUgMjU0LjE1OSA2OS4wODkgMjU1LjY2OSA2OC40MzJDMjU3LjE3OCA2Ny43NzUxIDI1OC41MzcgNjYuODEzOSAyNTkuNjYgNjUuNjA4MkwzMTEuMzE4IDEwLjEwNjlDMzEyLjExNSA5LjI1MTA3IDMxMi42NDUgOC4xODA1NiAzMTIuODQzIDcuMDI2OTVDMzEzLjA0MSA1Ljg3MzM0IDMxMi44OTkgNC42ODY4NiAzMTIuNDMzIDMuNjEzM0MzMTEuOTY3IDIuNTM5NzQgMzExLjE5OSAxLjYyNTg2IDMxMC4yMjEgMC45ODM5NDFDMzA5LjI0NCAwLjM0MjAyNiAzMDguMTAxIDMuOTUzMTRlLTA1IDMwNi45MzMgMEw2Mi4wNTk1IDBDNjAuNDE3OCAwLjAwMjc5ODY2IDU4Ljc5NDMgMC4zNDMxNCA1Ny4yODkzIDAuOTk5OTUzQzU1Ljc4NDMgMS42NTY3NyA1NC40Mjk5IDIuNjE2MDcgNTMuMzA5OSAzLjgxODQ3TDEuNjI1NzYgNTkuMzE5N0MwLjgyOTM2MSA2MC4xNzQ4IDAuMjk5MzU5IDYxLjI0NCAwLjEwMDc1MiA2Mi4zOTY0Qy0wLjA5Nzg1MzkgNjMuNTQ4OCAwLjA0MzU2OTggNjQuNzM0MiAwLjUwNzY3OSA2NS44MDczQzAuOTcxNzg5IDY2Ljg4MDMgMS43Mzg0MSA2Ny43OTQzIDIuNzEzNTIgNjguNDM3MkMzLjY4ODYzIDY5LjA4MDIgNC44Mjk4NCA2OS40MjQgNS45OTcxOSA2OS40MjY3WiIgZmlsbD0idXJsKCNwYWludDBfbGluZWFyXzQ3Nl8yNDMwKSIvPgo8L2c+CjxkZWZzPgo8bGluZWFyR3JhZGllbnQgaWQ9InBhaW50MF9saW5lYXJfNDc2XzI0MzAiIHgxPSIyNi40MTUiIHkxPSIyODcuMDU5IiB4Mj0iMjgzLjczNSIgeTI9Ii0yLjQ5NTc0IiBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSI+CjxzdG9wIG9mZnNldD0iMC4wOCIgc3RvcC1jb2xvcj0iIzk5NDVGRiIvPgo8c3RvcCBvZmZzZXQ9IjAuMyIgc3RvcC1jb2xvcj0iIzg3NTJGMyIvPgo8c3RvcCBvZmZzZXQ9IjAuNSIgc3RvcC1jb2xvcj0iIzU0OTdENSIvPgo8c3RvcCBvZmZzZXQ9IjAuNiIgc3RvcC1jb2xvcj0iIzQzQjRDQSIvPgo8c3RvcCBvZmZzZXQ9IjAuNzIiIHN0b3AtY29sb3I9IiMyOEUwQjkiLz4KPHN0b3Agb2Zmc2V0PSIwLjk3IiBzdG9wLWNvbG9yPSIjMTlGQjlCIi8+CjwvbGluZWFyR3JhZGllbnQ+CjxjbGlwUGF0aCBpZD0iY2xpcDBfNDc2XzI0MzAiPgo8cmVjdCB3aWR0aD0iMzEyLjkzIiBoZWlnaHQ9IjI4MC4zNzciIGZpbGw9IndoaXRlIi8+CjwvY2xpcFBhdGg+CjwvZGVmcz4KPC9zdmc+Cg==&color=9945FF" /></a>
+{% if clients.includes('js') %}
+<a href="https://www.npmjs.com/package/@{{ organizationName }}/{{ jsClientPackageName }}"><img src="https://img.shields.io/npm/v/%40{{ organizationName }}%2F{{ jsClientPackageName }}?logo=npm&color=377CC0" /></a>
+{% endif %}
+{% if clients.includes('rust') %}
+<a href="https://crates.io/crates/{{ rustClientCrateName }}"><img src="https://img.shields.io/crates/v/{{ rustClientCrateName }}?logo=rust" /></a>
+{% else %}
+<a href="https://crates.io/crates/{{ programCrateName }}"><img src="https://img.shields.io/crates/v/{{ programCrateName }}?logo=rust" /></a>
+{% endif %}
+
+This template should help get you started developing Solana programs. Let's walk through this generated program repository and see what's included.
+
+## Project setup
+
+The first thing you'll want to do is install NPM dependencies which will allow you to access all the scripts and tools provided by this template.
+
+```sh
+{{ getNpmCommand("install") }}
+```
+
+## Managing programs
+
+You'll notice a `program` folder in the root of this repository. This is where your generated Solana program is located.
+
+Whilst only one program gets generated, not that you can have as many programs as you like in this repository.
+Whenever you add a new program folder to this repository, remember to add it to the `members` array of your root `Cargo.toml` file.
+That way, your programs will be recognized by the following scripts that allow you to build, test, format and lint your programs respectively.
 
 ```sh
 {{ getNpmCommand("programs:build") }}
@@ -9,4 +37,81 @@ TODO
 {{ getNpmCommand("programs:lint") }}
 ```
 
-TODO
+## Generating IDLs
+
+You may use the following command to generate the IDLs for your programs.
+
+```sh
+{{ getNpmCommand("generate:idls") }}
+```
+
+Depending on your program's framework, this will either use Shank or Anchor to generate the IDLs.
+Note that, to ensure IDLs are generated using the correct framework version, the specific version used by the program will be downloaded and used locally.
+
+{% if clients.length > 0 %}
+## Generating clients
+
+Once your programs' IDLs have been generated, you can generate clients for them using the following command.
+
+```sh
+{{ getNpmCommand("generate:clients") }}
+```
+
+Alternatively, you can use the `generate` script to generate both the IDLs and the clients at once.
+
+```sh
+{{ getNpmCommand("generate") }}
+```
+
+## Managing clients
+
+The following clients are available for your programs. You may use the following links to learn more about each client.
+
+{% for client in clients %}
+{% if ['js'].includes(client) %}
+- [{{ client | upper }} client](./clients/{{ client }})
+{% else %}
+- [{{ client | titleCase }} client](./clients/{{ client }})
+{% endif %}
+{% endfor %}
+
+## Starting and stopping the local validator
+
+The following script is available to start your local validator.
+
+```sh
+{{ getNpmCommand("validator") }}
+```
+
+By default, if a local validator is already running, the script will be skipped. You may use the `--restart` flag to force the validator to restart.
+
+```sh
+{{ getNpmCommand("validator", "--restart") }}
+```
+
+Finally, you may stop the local validator using the following command.
+
+```sh
+{{ getNpmCommand("validator:stop") }}
+```
+
+## Using external programs in your validator
+
+If your program requires any external programs to be running, you'll want to in your local validator.
+
+You can do this by adding their program addresses to the `program-dependencies` array in the `Cargo.toml` of your program.
+
+```toml
+program-dependencies = [
+  "metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s",
+  "noopb9bkMVfRPU8AsbpTUg8AQkHtKwMYZiFUjNRtMmV",
+]
+```
+
+Next time you build your program and run your validator, these external programs will automatically be fetched from mainnet and used in your local validator.
+
+```sh
+{{ getNpmCommand("programs:build") }}
+{{ getNpmCommand("validator", "--restart") }}
+```
+{% endif %}

template/clients/js/clients/js/README.md.njk

@@ -0,0 +1,38 @@
+# JavaScript client
+
+A generated JavaScript library for the {{ programName | titleCase }} program.
+
+## Getting started
+
+To build and test your JavaScript client from the root of the repository, you may use the following command.
+
+```sh
+{{ getNpmCommand("clients:js:test") }}
+```
+
+This will start a new local validator, if one is not already running, and run the tests for your JavaScript client.
+
+## Available client scripts.
+
+Alternatively, you can go into the client directory and run the tests directly.
+
+```sh
+# Build your programs and start the validator.
+{{ getNpmCommand("programs:build") }}
+{{ getNpmCommand("validator") }}
+
+# Go into the client directory and run the tests.
+cd clients/js
+{{ getNpmCommand("install") }}
+{{ getNpmCommand("build") }}
+{{ getNpmCommand("test") }}
+```
+
+You may also use the following scripts to lint and/or format your JavaScript client.
+
+```sh
+{{ getNpmCommand("lint") }}
+{{ getNpmCommand("lint:fix") }}
+{{ getNpmCommand("format") }}
+{{ getNpmCommand("format:fix") }}
+```

template/clients/rust/clients/rust/README.md.njk

@@ -0,0 +1,13 @@
+# Rust client
+
+A generated Rust library for the {{ programName | titleCase }} program.
+
+## Getting started
+
+To build and test your Rust client from the root of the repository, you may use the following command.
+
+```sh
+{{ getNpmCommand("clients:js:test") }}
+```
+
+This will start a new local validator, if one is not already running, and run the tests for your Rust client.

template/programs/counter-shank/program/README.md.njk

@@ -0,0 +1,3 @@
+# {{ programName | titleCase }}
+
+Your generated Solana program. Have fun!