diff --git a/daprdocs/content/en/contributing/contributing-docs.md b/daprdocs/content/en/contributing/contributing-docs.md index e8a4d5cb4..66d1c5881 100644 --- a/daprdocs/content/en/contributing/contributing-docs.md +++ b/daprdocs/content/en/contributing/contributing-docs.md @@ -219,6 +219,102 @@ brew install dapr/tap/dapr-cli {{< /tabs >}} +### Embedded code snippets + +Use the `code-snippet` shortcode to reference code snippets from the `static/code` directory. + +``` +{{}} +``` + +{{% alert title="Warning" color="warning" %}} +All Dapr sample code should be self-contained in separate files, not in markdown. Use the techniques described here to highlight the parts of the sample code users should focus on. +{{% /alert %}} + +Use the `lang` (default `txt`) parameter to configure the language used for syntax highlighting. + +Use the `marker` parameter to limit the embedded snipped to a portion of the sample file. This is useful when you want to show just a portion of a larger file. The typical way to do this is surround the interesting code with comments, and then pass the comment text into `marker`. + +The shortcode below and code sample: + +``` +{{}} +``` + +```python +import json +import time + +from dapr.clients import DaprClient + +#SAMPLE +with DaprClient() as d: + req_data = { + 'id': 1, + 'message': 'hello world' + } + + while True: + # Create a typed message with content type and body + resp = d.invoke_method( + 'invoke-receiver', + 'my-method', + data=json.dumps(req_data), + ) + + # Print the response + print(resp.content_type, flush=True) + print(resp.text(), flush=True) + + time.sleep(2) +#SAMPLE +``` + +Will result in the following output: + +{{< code-snippet file="contributing-1.py" lang="python" marker="#SAMPLE" >}} + +Use the `replace-key-[token]` and `replace-value-[token]` parameters to limit the embedded snipped to a portion of the sample file. This is useful when you want abbreviate a portion of the code sample. Multiple replacements are supported with multiple values of `token`. + +The shortcode below and code sample: + +``` +{{}} +``` + +```python +#IMPORTS +import json +import time +#IMPORTS + +from dapr.clients import DaprClient + +with DaprClient() as d: + req_data = { + 'id': 1, + 'message': 'hello world' + } + + while True: + # Create a typed message with content type and body + resp = d.invoke_method( + 'invoke-receiver', + 'my-method', + data=json.dumps(req_data), + ) + + # Print the response + print(resp.content_type, flush=True) + print(resp.text(), flush=True) + + time.sleep(2) +``` + +Will result in the following output: + +{{< code-snippet file="./contributing-2.py" lang="python" replace-key-imports="#IMPORTS" replace-value-imports="# Import statements" >}} + ### YouTube videos Hugo can automatically embed YouTube videos using a shortcode: ``` diff --git a/daprdocs/layouts/shortcodes/code-snippet.html b/daprdocs/layouts/shortcodes/code-snippet.html new file mode 100644 index 000000000..a561b0bb9 --- /dev/null +++ b/daprdocs/layouts/shortcodes/code-snippet.html @@ -0,0 +1,23 @@ +{{ $file := .Get "file" }} +{{ $filePath := (path.Join "/static/code/" $file ) }} +{{ $fileContents := $filePath | readFile }} +{{ $lang := .Get "lang" | default "txt" }} +{{ $embed := .Get "embed" | default true }} +{{ if $embed }} +{{ if isset .Params "marker" }} + {{ $marker := .Get "marker" }} + {{ $regex := printf "(?s).*%s%s%s.*" $marker `(\n)?(?P.*?)(\n\s+)?` $marker }} + {{ $fileContents = replaceRE $regex "$inner" $fileContents}} +{{ end }} +{{ range $key, $value := $.Params }} + {{ if hasPrefix $key "replace-key" }} + {{ $replace := $value }} + {{ $replaceValueParameter := printf "replace-value-%s" (slicestr $key (len "replace-key-")) }} +

{{ $replaceValueParameter }}

+ {{ $replaceWith := index $.Params $replaceValueParameter }} + {{ $regex := printf "(?s)%s%s%s" $replace `(\n)?(?P.*?)(\n\s+)?` $replace }} + {{ $fileContents = replaceRE $regex $replaceWith $fileContents}} + {{ end }} +{{ end }} +{{ (print "```" $lang "\n" $fileContents "\n```") | markdownify }} +{{ end }} diff --git a/daprdocs/static/code/contributing-1.py b/daprdocs/static/code/contributing-1.py new file mode 100644 index 000000000..98c06c60a --- /dev/null +++ b/daprdocs/static/code/contributing-1.py @@ -0,0 +1,26 @@ +import json +import time + +from dapr.clients import DaprClient + +#SAMPLE +with DaprClient() as d: + req_data = { + 'id': 1, + 'message': 'hello world' + } + + while True: + # Create a typed message with content type and body + resp = d.invoke_method( + 'invoke-receiver', + 'my-method', + data=json.dumps(req_data), + ) + + # Print the response + print(resp.content_type, flush=True) + print(resp.text(), flush=True) + + time.sleep(2) +#SAMPLE diff --git a/daprdocs/static/code/contributing-2.py b/daprdocs/static/code/contributing-2.py new file mode 100644 index 000000000..9a55ed5d2 --- /dev/null +++ b/daprdocs/static/code/contributing-2.py @@ -0,0 +1,26 @@ +#IMPORTS +import json +import time +#IMPORTS + +from dapr.clients import DaprClient + +with DaprClient() as d: + req_data = { + 'id': 1, + 'message': 'hello world' + } + + while True: + # Create a typed message with content type and body + resp = d.invoke_method( + 'invoke-receiver', + 'my-method', + data=json.dumps(req_data), + ) + + # Print the response + print(resp.content_type, flush=True) + print(resp.text(), flush=True) + + time.sleep(2)