[Examples] Contributing.md in examples. (microsoft#146)

Fine grained by GPT

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.

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
 

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

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

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
 

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
 

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: