Basic Usage Example

You can think of this section in two ways:

1. This is what people can run to test that they have installed the tool correctly.
2. Showing what your tool can do via the most simple possible example – anything more complex should go in a tutorial/how-to guide/example in the external documentation.

Writing Tips: If you’re having trouble deciding what to use here:

• What have you been doing to test that your code is working? This might be a good place to start.
• Even if it doesn’t show off the capabilities of your tool, what is the fastest thing a user can run and still get an output?
• What is an example requires the fewest input requirements? This will make it easier to write and maintain.

You can have multiple usage examples, but if your README starts to feel long, consider putting all but one or two of them somewhere in the external documentation instead.

The usage examples should include

• 1-2 sentence summary of what the example does
• Any necessary input files and where the user can find/generate them
• Any outputfiles and where to find examples (This allows the user to compare their outputs to make sure they have the tool installed correctly.)
• A list of every step the user needs to follow to run the example successfully

Writing Tip: Make sure to use code blocks or in-line code when applicable! To see how to do this in markdown, look at myst-md-demo in the companion repository.