diff --git a/examples/CONTRIBUTING.md b/examples/CONTRIBUTING.md new file mode 100644 index 00000000000..c8625e2303d --- /dev/null +++ b/examples/CONTRIBUTING.md @@ -0,0 +1,52 @@ +# Contributing to examples folder + +Thank you for your interest in contributing to the examples folder. This folder contains a collection of Python notebooks and selected markdown files that demonstrate various usage of this promptflow project. The script will automatically generate a README.md file in the root folder, listing all the notebooks and markdown files with their corresponding workflows. + +## Guidelines for notebooks and markdown files in examples folder + +When creating or modifying a notebook or markdown file, please follow these guidelines: + +- Each notebook or markdown file should have a clear and descriptive title as the first line +- Each notebook or markdown file should have a brief introduction that explains the purpose and scope of the example. For details, please refer to the readme workflow generator manual [README.md](../scripts/readme/README.md) file. + - The first sentence of first paragraph of the markdown file is important. The introduction should be concise and informative, and end with a period. + - Each notebook file should have a metadata area when the file is opened as a big JSON file. The metadata area may contain the following fields: + - `.metadata.description`: (Mandatory) A short description of the example that will be displayed in the README.md file. The description should be concise and informative, and end with a period. + - `.metadata.stage`: (Optional) A value that indicates whether the script should skip generating a workflow for this notebook or markdown file. If set to `development`, the script will ignore this file. If set to other values or omitted, the script will generate a workflow for this file. +- Each notebook or markdown file should have a clear and logical structure, using appropriate headings, subheadings, comments, and code cells. The code cells should be executable and produce meaningful outputs. +- Each notebook or markdown file should follow the [PEP 8] style guide for Python code, and use consistent and readable variable names, indentation, spacing, and punctuation. +- Each notebook or markdown file should include relevant references, citations, and acknowledgements + +## Generate workflows, update README.md and submit pull requests + +To run the readme.py script, you need to have Python 3 installed on your system. You also need to install the required packages by running: + +```bash +# At this examples folder +pip install -r requirements.txt +pip install -r dev_requirements.txt +``` + +Then, you can run the script by: + +```bash +# At the root of this repository +python scripts/readme/readme.py +``` + +For detailed usage of readme.py, please refer to the readme workflow generator manual [README.md](../scripts/readme/README.md) + +### Update [README.md](./README.md) in [examples](./) folder + +The readme.py script will scan all the notebooks and markdown files in the examples folder, and generate a README.md file in the root folder. The README.md file will contain a table of contents with links to each notebook and markdown file, as well as their descriptions and workflows. + +### Generations in the [workflows](../.github/workflows/) folder + +This contains two parts: +* For notebooks, we'll prepare standard workflow running environment to test the notebook to the end. +* For markdowns, The workflows are generated by extracting the `bash` cells from markdown file. The workflows will prepare standard workflow running environment and test these cells to the end. + +The script will also save workflows in the [workflows](../.github/workflows/) folder, where each notebook or markdown file will have a corresponding workflow file with the `.yml` extension. The workflow files can be triggered by creating a new pull request or pushing a new commit to the repository. The workflow will run the notebook or markdown file, and you could check the outputs afterwards. + +## Feedback and Support + +If you have any feedback or need any support regarding this folder, submit an issue on GitHub. We appreciate your contribution and hope you enjoy using our project. \ No newline at end of file diff --git a/examples/README.md b/examples/README.md index 9e2cd3764d9..1a5e87db3c8 100644 --- a/examples/README.md +++ b/examples/README.md @@ -91,10 +91,11 @@ | [chat-with-pdf.ipynb](flows/chat/chat-with-pdf) | [![samples_flows_chat_chatwithpdf_chatwithpdf](https://github.com/microsoft/promptflow/actions/workflows/samples_flows_chat_chatwithpdf_chatwithpdf.yml/badge.svg?branch=main)](https://github.com/microsoft/promptflow/actions/workflows/samples_flows_chat_chatwithpdf_chatwithpdf.yml) | A tutorial of chat-with-pdf flow that allows user ask questions about the content of a PDF file and get answers | - ## Contributing -We welcome contributions and suggestions! Please see the [contributing guidelines](../CONTRIBUTING.md) for details. +We welcome contributions and suggestions to examples folder! Please see the [CONTRIBUTING.md](./CONTRIBUTING.md) for details. + +Please DO NOT directly change this README.md file since this README is generated by script. Manual changes will be overwritten on regeneration. ## Code of Conduct diff --git a/examples/flows/chat/chat-with-pdf/chat-with-pdf-azure.ipynb b/examples/flows/chat/chat-with-pdf/chat-with-pdf-azure.ipynb index 4c7b306c77c..52d1ab65d28 100644 --- a/examples/flows/chat/chat-with-pdf/chat-with-pdf-azure.ipynb +++ b/examples/flows/chat/chat-with-pdf/chat-with-pdf-azure.ipynb @@ -249,7 +249,7 @@ "pygments_lexer": "ipython3", "version": "3.9.17" }, - "no_readme_generation": "true" + "stage": "development" }, "nbformat": 4, "nbformat_minor": 2 diff --git a/examples/flows/chat/chat-with-pdf/chat_with_pdf/test.ipynb b/examples/flows/chat/chat-with-pdf/chat_with_pdf/test.ipynb index 464e52054ca..ac1a3189305 100644 --- a/examples/flows/chat/chat-with-pdf/chat_with_pdf/test.ipynb +++ b/examples/flows/chat/chat-with-pdf/chat_with_pdf/test.ipynb @@ -53,7 +53,7 @@ "pygments_lexer": "ipython3", "version": "3.9.17" }, - "no_readme_generation": "true" + "stage": "development" }, "nbformat": 4, "nbformat_minor": 2 diff --git a/scripts/readme/README.md b/scripts/readme/README.md index 230fface3cf..7ef44bbb6e8 100644 --- a/scripts/readme/README.md +++ b/scripts/readme/README.md @@ -40,7 +40,7 @@ Multiple inputs are supported. ### 3.1 Notebook Workflow Generation * Each workflow contains metadata area, set `.metadata.description` area will display this message in the corresponding cell in [README.md](../../examples/README.md) file. -* When set `.metadata.no_readme_generation` to value `true`, the script will stop generating for this notebook. +* When set `.metadata.stage` to value `development`, the script will stop generating for this notebook. ### 3.2 README.md Workflow Generation diff --git a/scripts/readme/ghactions_driver/readme_templates/README.md.jinja2 b/scripts/readme/ghactions_driver/readme_templates/README.md.jinja2 index b28f91a6c2b..b5a40fb5ee3 100644 --- a/scripts/readme/ghactions_driver/readme_templates/README.md.jinja2 +++ b/scripts/readme/ghactions_driver/readme_templates/README.md.jinja2 @@ -81,10 +81,11 @@ {%- if flows.notebooks|length > 0 -%}{% for flow in flows.notebooks %}| [{{ flow.name }}]({{ flow.path }}) | [![{{flow.pipeline_name}}](https://github.com/microsoft/promptflow/actions/workflows/{{flow.yaml_name}}/badge.svg?branch={{branch}})](https://github.com/microsoft/promptflow/actions/workflows/{{flow.yaml_name}}) | {{ flow.description }} | {% endfor %}{% endif %} - ## Contributing -We welcome contributions and suggestions! Please see the [contributing guidelines](../CONTRIBUTING.md) for details. +We welcome contributions and suggestions to examples folder! Please see the [CONTRIBUTING.md](./CONTRIBUTING.md) for details. + +Please DO NOT directly change this README.md file since this README is generated by script. Manual changes will be overwritten on regeneration. ## Code of Conduct diff --git a/scripts/readme/workflow_generator.py b/scripts/readme/workflow_generator.py index d1cfac1108b..532bf2f4da4 100644 --- a/scripts/readme/workflow_generator.py +++ b/scripts/readme/workflow_generator.py @@ -124,16 +124,16 @@ def local_filter(callback, array): def no_readme_generation_filter(item, index, array) -> bool: """ - Set each ipynb metadata no_readme_generation to "true" to skip readme generation + Set each ipynb metadata stage to "development" to skip readme generation """ try: # read in notebook with open(item, "r", encoding="utf-8") as f: data = json.load(f) try: - if data["metadata"]["no_readme_generation"] is not None: + if data["metadata"]["stage"] is not None: # no_readme_generate == "true", then no generation - return data["metadata"]["no_readme_generation"] != "true" + return data["metadata"]["stage"] != "development" except Exception: return True # generate readme except Exception: