# reformat-all-commands.sh

Calls `reformat.py` and `convert_swagger.py` to populate the "reference-docs" structure. Requires two arguments be passed referencing the source code of _go-algorand_ and _indexer_ respectively:

`./reformat-all-commands.sh $GO_ALGORAND_SRC $INDEXER_SRC`

# reformat.py

Reformats markdown generated by the go spf13/cobra library to work with mkdocs.

Given the `goal` in the path, regenerate the docs from this directory by running:
```
rm -rf ../docs/Reference-Docs/goal
mkdir ../docs/Reference-Docs/goal
goal generate-docs ../docs/Reference-Docs/goal
./reformat.py -path ../docs/Reference-Docs/goal -cmd goal
```

# convert_swagger.py

Given a swagger specfile, generates a markdown file.
Currently uses `swagger2markup`, with some post processing to make
the markdown more pleasant with our mkdocs theme.

```
./convert_swagger.py -specfile ~/algorand/indexer/api/indexer.oas2.json  -target ../docs/reference/rest-apis/indexer.md
./convert_swagger.py -specfile ~/go/src/github.com/algorand/go-algorand/daemon/kmd/api/swagger.json  -target ../docs/reference/rest-apis/kmd.md
./convert_swagger.py -specfile ~/go/src/github.com/algorand/go-algorand/daemon/algod/api/algod.oas2.json  -target ../docs/reference/rest-apis/algod.md
```

# config_json_gen

Used to extract node config options from the go-algorand source. Markdown is written to stdout, warnings are written to stderr. To update the template, edit template.tmpl and rebuild the tool.

Build tool:
```
go build .
```

Run:
```
./config_json_gen -path ~/algorand/go-algorand/ > ../../docs/run-a-node/reference/config.md
```

All in one:
```
go run main.go -path ~/algorand/go-algorand/ > ../../docs/run-a-node/reference/config.md
```

# Code examples

## Example formatting

Examples are all named descriptively and may be referenced in the markdown in multiple places if necessary.

The format for a named example in the docs markdown is:
```
<!-- ===LANGSDK_EXAMPLENAME=== -->
<!-- ===LANGSDK_EXAMPLENAME=== -->
```
Running the import script will replace any text between these two tags with the matching example from the SDK repos.

A file containing all examples with descriptions is in `example_tracker/example_list.md`.
A script that is helpful to track any examples that are missing from languages (or typo'd) is in `example_tracker/list_examples.sh`.

To ensure the language tabs display correctly the markdown must be formatted as follows:
```
=== "LanguageName"
    <!-- ===LANGSDK_EXAMPLE_NAME=== -->
    <!-- ===LANGSDK_EXAMPLE_NAME=== -->
```

That is, the comment flags must be tabbed over under the `=== "LanguageName"` line.



## Running the import script

The import script, `import_examples.py`, will search the configured repository paths for named examples to be pulled into the docs. The script will clone the SDK repositories if they are not already present. The script will also update the SDK repositories if they are already present.

The following will import only the `PYSDK` examples:
```sh
python import_examples.py --src PYSDK
```

## New examples

For any *new* examples, please follow the formatting of the existing examples in that repository.

The `examples` branch of all the SDKs should be used for development of examples.  The examples should be runable with the smoke-test shell script, so that CI can catch any issues.
