From 852987c744ae424582ca92d1f2b8b3ad3b46a7e2 Mon Sep 17 00:00:00 2001 From: Dave Date: Wed, 3 Apr 2024 12:32:42 +0200 Subject: [PATCH] update contributing --- docs/examples/CONTRIBUTING.md | 51 ++++++++++------------------------- 1 file changed, 14 insertions(+), 37 deletions(-) diff --git a/docs/examples/CONTRIBUTING.md b/docs/examples/CONTRIBUTING.md index 3837300a2b..625a09d9c0 100644 --- a/docs/examples/CONTRIBUTING.md +++ b/docs/examples/CONTRIBUTING.md @@ -4,50 +4,27 @@ Note: All paths in this guide are relative to the `dlt` repository directory. ## Add snippet -- Go to `docs/website/docs/examples/`. -- Copy one of the examples, rename scripts. -- Modify the script in `/code/-snippets.py`: - - The whole example code should be inside of `def _snippet()` function. - - Use tags `# @@@DLT_SNIPPET_START example` and `# @@@DLT_SNIPPET_END example` to indicate which part of the code will be auto-generated in the final script `docs/examples//.py`. - - Use additional tags as `# @@@DLT_SNIPPET_START smal_part_of_code` to indicate which part of the code will be auto-inserted into a text document `docs/website/docs/examples//index.md` in the form of a code snippet. -- Modify .`dlt/secrets.toml` and `configs.toml` if needed. -- Modify `/index.md`: - - In the section `
`. - - List what users will learn from this example. Use bullet points and link corresponding documentation pages. - - Use tags `` to insert example code snippets. Do not write them manually! - -## Add tests - -- Do not forget to add tests to `/code/-snippets.py`. -- They could be short asserts, code should work. -- Use `# @@@DLT_REMOVE` to remove test code from final code example. -- Test your snippets locally first with command: - - `cd docs/website/docs/examples//code && pytest --ignore=node_modules -s -v`. -- Add `@skipifgithubfork` decorator to your main snippet function, look [example](https://github.com/dlt-hub/dlt/blob/master/docs/website/docs/examples/chess_production/code/chess-snippets.py#L1-L4). - -## Run npm start +- Go to `docs/examples/`. +- Copy the template in `./_template/..`. +- Make sure the folder and your examples script have the same name +- Update the doc string which will compromise the generated markdown file, check the other examples how it is done +- If your example requires any secrets, add the vars to the example.secrects.toml but do not enter the values. +- Add your example code, make sure you have a `if __name__ = "__main__"` clause in which you run the example script, this will be used for testing +- You should add one or two assertions after running your example and maybe also `load_info.raise_on_failed_jobs()`, this will help greatly with testing + +## Testing +- You can test your example simply by running your example script from your example folder. On CI a test will be automatically generated. + +## Checking your generated markdown The command `npm start` starts a local development server and opens up a browser window. - To install npm read [README](../website/README.md). -- This command will generate a clean example script in `docs/examples/` folder based on `docs/website/docs/examples//code/-snippets.py`. -- Also, this command automatically inserts code snippets to `docs/website/docs/examples//index.md`. +- You should your example be automatically added to the examples section in the local version of the docs. Check the rendered output and see wether it looks the way you intended. ## Add ENV variables -If you use any secrets for the code snippets, e.g. Zendesk requires credentials. You need to add them to GitHub Actions in ENV style: - -- First, add the variables to `.github/workflows/test_doc_snippets.yml`: - - Example: - - ```yaml - # zendesk vars for example - SOURCES__ZENDESK__CREDENTIALS: ${{ secrets.ZENDESK__CREDENTIALS }} - ``` - -- Ask dlt team to add them to the GitHub Secrets. +If you use any secrets for the code snippets, e.g. Zendesk requires credentials. Please talk to us. We will add them to our google secrets vault. ## Add dependencies