Merge pull request #2674 from Textualize/add-faq

Add FAQ

.faq/FAQ.md

@@ -0,0 +1,20 @@
+
+# Frequently Asked Questions 
+
+{%- for question in questions %}
+- [{{ question.title }}](#{{ question.slug }})
+{%- endfor %}
+
+
+{%- for question in questions %}
+
+<a name="{{ question.slug }}"></a>
+## {{ question.title }}
+
+{{ question.body }}
+
+{%- endfor %}
+
+<hr>
+
+Generated by [FAQtory](https://github.com/willmcgugan/faqtory)

.faq/suggest.md

@@ -0,0 +1,20 @@
+{%- if questions -%}
+{% if questions|length == 1 %}
+We found the following entry in the [FAQ]({{ faq_url }}) which you may find helpful:
+{%- else %}
+We found the following entries in the [FAQ]({{ faq_url }}) which you may find helpful:
+{%- endif %}
+
+{% for question in questions %}
+- [{{ question.title }}]({{ faq_url }}#{{ question.slug }})
+{%- endfor %}
+
+Feel free to close this issue if you found an answer in the FAQ. Otherwise, please give us a little time to review.
+
+{%- else -%}
+Thank you for your issue. Give us a little time to review it.
+
+PS. You might want to check the [FAQ]({{ faq_url }}) if you haven't done so already.
+{%- endif %}
+
+This is an automated reply, generated by [FAQtory](https://github.com/willmcgugan/faqtory)

.github/workflows/newissue.yml

@@ -0,0 +1,27 @@
+name: issues
+on:
+  issues:
+    types: [opened]
+jobs:
+  add-comment:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          ref: main
+      - name: Install FAQtory
+        run: pip install FAQtory
+      - name: Run Suggest
+        run: faqtory suggest "${{ github.event.issue.title }}" > suggest.md
+      - name: Read suggest.md
+        id: suggest
+        uses: juliangruber/read-file-action@v1
+        with:
+          path: ./suggest.md
+      - name: Suggest FAQ
+        uses: peter-evans/create-or-update-comment@a35cf36e5301d70b76f316e867e7788a55a31dae
+        with:
+          issue-number: ${{ github.event.issue.number }}
+          body: ${{ steps.suggest.outputs.content }}

FAQ.md

@@ -0,0 +1,43 @@
+
+# Frequently Asked Questions
+- [Why does emoji break alignment in a Table or Panel?](#why-does-emoji-break-alignment-in-a-table-or-panel)
+- [Why does content in square brackets disappear?](#why-does-content-in-square-brackets-disappear)
+- [python -m rich.spinner shows extra lines](#python--m-rich.spinner-shows-extra-lines)
+- [Strange colors in console output.](#strange-colors-in-console-output.)
+
+<a name="why-does-emoji-break-alignment-in-a-table-or-panel"></a>
+## Why does emoji break alignment in a Table or Panel?
+
+Certain emoji take up double space within the terminal. Unfortunately, terminals don't always agree how wide a given character should be.
+
+Rich has no way of knowing how wide a character will be on any given terminal. This can break alignment in containers like Table and Panel, where Rich needs to know the width of the content.
+
+There are also *multiple codepoints* characters, such as country flags, and emoji modifiers, which produce wildly different results across terminal emulators. 
+
+Fortunately, most characters will work just fine. But you may have to avoid using the emojis that break alignment. You will get good results if you stick to emoji released on or before version 9 of the Unicode database,
+
+<a name="why-does-content-in-square-brackets-disappear"></a>
+## Why does content in square brackets disappear?
+
+Rich will treat text within square brackets as *markup tags*, for instance `"[bold]This is bold[/bold]"`.
+
+If you are printing strings with literally square brackets you can either disable markup, or escape your strings.
+See the docs on [console markup](https://rich.readthedocs.io/en/latest/markup.html) for how to do this.
+
+<a name="python--m-rich.spinner-shows-extra-lines"></a>
+## python -m rich.spinner shows extra lines
+
+The spinner example is know to break on some terminals (Windows in particular).
+
+Some terminals don't display emoji with the correct width, which means Rich can't always align them accurately inside a panel.
+
+<a name="strange-colors-in-console-output."></a>
+## Strange colors in console output.
+
+Rich will highlight certain patterns in your output such as numbers, strings, and other objects like IP addresses.
+
+Occasionally this may also highlight parts of your output you didn't intend. See the [docs on highlighting](https://rich.readthedocs.io/en/latest/highlighting.html) for how to disable highlighting.
+
+<hr>
+
+Generated by [FAQtory](https://github.com/willmcgugan/faqtory)

faq.yml

@@ -0,0 +1,7 @@
+# FAQtory settings
+
+faq_url: "https://github.com/textualize/rich/blob/main/FAQ.md" # Replace this with the URL to your FAQ.md!
+
+questions_path: "./questions" # Where questions should be stored
+output_path: "./FAQ.md" # Where FAQ.md should be generated 
+templates_path: ".faq" # Path to templates

questions/README.md

@@ -0,0 +1,6 @@
+
+# Questions
+
+Your questions should go in this directory.
+
+Question files should be named with the extension ".question.md".

questions/emoji_broken.question.md

@@ -0,0 +1,11 @@
+---
+title: "Why does emoji break alignment in a Table or Panel?"
+---
+
+Certain emoji take up double space within the terminal. Unfortunately, terminals don't always agree how wide a given character should be.
+
+Rich has no way of knowing how wide a character will be on any given terminal. This can break alignment in containers like Table and Panel, where Rich needs to know the width of the content.
+
+There are also *multiple codepoints* characters, such as country flags, and emoji modifiers, which produce wildly different results across terminal emulators. 
+
+Fortunately, most characters will work just fine. But you may have to avoid using the emojis that break alignment. You will get good results if you stick to emoji released on or before version 9 of the Unicode database, 

questions/highlighting_unexpected.question.md

@@ -0,0 +1,9 @@
+---
+title: "Strange colors in console output."
+alt_titles:
+  - "Why are numbers in cyan?"
+---
+
+Rich will highlight certain patterns in your output such as numbers, strings, and other objects like IP addresses.
+
+Occasionally this may also highlight parts of your output you didn't intend. See the [docs on highlighting](https://rich.readthedocs.io/en/latest/highlighting.html) for how to disable highlighting.

questions/rich_spinner.question.md

@@ -0,0 +1,7 @@
+---
+title: "python -m rich.spinner shows extra lines"
+---
+
+The spinner example is know to break on some terminals (Windows in particular).
+
+Some terminals don't display emoji with the correct width, which means Rich can't always align them accurately inside a panel.

questions/square_brackets.question.md

@@ -0,0 +1,10 @@
+---
+title: "Why does content in square brackets disappear?"
+alt_titles:
+    - "Can not print a [string]"
+---
+
+Rich will treat text within square brackets as *markup tags*, for instance `"[bold]This is bold[/bold]"`.
+
+If you are printing strings with literally square brackets you can either disable markup, or escape your strings.
+See the docs on [console markup](https://rich.readthedocs.io/en/latest/markup.html) for how to do this.