Merge pull request #3129 from davep/faq-in-docs

Move the Textual FAQ into the main docs

Author: davep

.faq/FAQ.md

@@ -1,16 +1,15 @@
+---
+hide:
+  - navigation
+---
+
 <!-- Auto-generated by FAQtory -->
 <!-- Do not edit by hand! -->
 
 # 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 }}

Makefile

@@ -28,6 +28,10 @@ format-check:
 clean-screenshot-cache:
 	rm -rf .screenshot_cache
 
+.PHONY: faq
+faq:
+	$(run) faqtory build
+
 .PHONY: docs-offline-nav
 docs-offline-nav:
 	echo "INHERIT: mkdocs-offline.yml" > mkdocs-nav-offline.yml
@@ -67,10 +71,6 @@ docs-deploy: clean-screenshot-cache docs-online-nav
 	$(run) mkdocs gh-deploy --config-file mkdocs-nav-online.yml
 	rm -f mkdocs-nav-online.yml
 
-.PHONY: faq
-faq:
-	$(run) faqtory build
-
 .PHONY: build
 build: docs-build-offline
 	poetry build

FAQ.md renamed to docs/FAQ.md

@@ -1,28 +1,19 @@
+---
+hide:
+  - navigation
+---
+
 <!-- Auto-generated by FAQtory -->
 <!-- Do not edit by hand! -->
 
 # Frequently Asked Questions
-- [Does Textual support images?](#does-textual-support-images)
-- [How can I fix ImportError cannot import name ComposeResult from textual.app ?](#how-can-i-fix-importerror-cannot-import-name-composeresult-from-textualapp-)
-- [How can I select and copy text in a Textual app?](#how-can-i-select-and-copy-text-in-a-textual-app)
-- [How can I set a translucent app background?](#how-can-i-set-a-translucent-app-background)
-- [How do I center a widget in a screen?](#how-do-i-center-a-widget-in-a-screen)
-- [How do I fix WorkerDeclarationError?](#how-do-i-fix-workerdeclarationerror)
-- [How do I pass arguments to an app?](#how-do-i-pass-arguments-to-an-app)
-- [No widget called TextLog](#no-widget-called-textlog)
-- [Why do some key combinations never make it to my app?](#why-do-some-key-combinations-never-make-it-to-my-app)
-- [Why doesn't Textual look good on macOS?](#why-doesn't-textual-look-good-on-macos)
-- [Why doesn't Textual support ANSI themes?](#why-doesn't-textual-support-ansi-themes)
-- [Why doesn't the `DataTable` scroll programmatically?](#why-doesn't-the-`datatable`-scroll-programmatically)
-
-<a name="does-textual-support-images"></a>
+
 ## Does Textual support images?
 
 Textual doesn't have built-in support for images yet, but it is on the [Roadmap](https://textual.textualize.io/roadmap/).
 
 See also the [rich-pixels](https://github.com/darrenburns/rich-pixels) project for a Rich renderable for images that works with Textual.
 
-<a name="how-can-i-fix-importerror-cannot-import-name-composeresult-from-textualapp-"></a>
 ## How can I fix ImportError cannot import name ComposeResult from textual.app ?
 
 You likely have an older version of Textual. You can install the latest version by adding the `-U` switch which will force pip to upgrade.
@@ -33,7 +24,6 @@ The following should do it:
 pip install textual-dev -U
 ```
 
-<a name="how-can-i-select-and-copy-text-in-a-textual-app"></a>
 ## How can I select and copy text in a Textual app?
 
 Running a Textual app puts your terminal in to *application mode* which disables clicking and dragging to select text.
@@ -46,7 +36,6 @@ may expect from the command line. The exact modifier key depends on the terminal
 
 Refer to the documentation for your terminal emulator, if it is not listed above.
 
-<a name="how-can-i-set-a-translucent-app-background"></a>
 ## How can I set a translucent app background?
 
 Some terminal emulators have a translucent background feature which allows the desktop underneath to be partially visible.
@@ -56,7 +45,6 @@ Textual uses 16.7 million colors where available which enables consistent colors
 
 For more information on ANSI colors in Textual, see [Why no Ansi Themes?](#why-doesnt-textual-support-ansi-themes).
 
-<a name="how-do-i-center-a-widget-in-a-screen"></a>
 ## How do I center a widget in a screen?
 
 To center a widget within a container use
@@ -146,7 +134,6 @@ if __name__ == "__main__":
     ButtonApp().run()
 ```
 
-<a name="how-do-i-fix-workerdeclarationerror"></a>
 ## How do I fix WorkerDeclarationError?
 
 Textual version 0.31.0 requires that you set `thread=True` on the `@work` decorator if you want to run a threaded worker.
@@ -169,7 +156,6 @@ async def run_in_background():
 
 This change was made because it was too easy to accidentally create a threaded worker, which may produce unexpected results.
 
-<a name="how-do-i-pass-arguments-to-an-app"></a>
 ## How do I pass arguments to an app?
 
 When creating your `App` class, override `__init__` as you would when
@@ -203,7 +189,6 @@ Greetings(to_greet="davep").run()
 Greetings("Well hello", "there").run()
 ```
 
-<a name="no-widget-called-textlog"></a>
 ## No widget called TextLog
 
 The `TextLog` widget was renamed to `RichLog` in Textual 0.32.0.
@@ -216,7 +201,6 @@ Here's how you should import RichLog:
 from textual.widgets import RichLog
 ```
 
-<a name="why-do-some-key-combinations-never-make-it-to-my-app"></a>
 ## Why do some key combinations never make it to my app?
 
 Textual can only ever support key combinations that are passed on by your
@@ -246,7 +230,6 @@ If you need to test what [key
 combinations](https://textual.textualize.io/guide/input/#keyboard-input)
 work in different environments you can try them out with `textual keys`.
 
-<a name="why-doesn't-textual-look-good-on-macos"></a>
 ## Why doesn't Textual look good on macOS?
 
 You may find that the default macOS Terminal.app doesn't render Textual apps (and likely other TUIs) very well, particuarily when it comes to box characters.
@@ -282,7 +265,6 @@ We recommend any of the following terminals:
 
 <img width="1002" alt="Screenshot 2023-06-19 at 11 00 25" src="https://github.com/Textualize/textual/assets/554369/9a8cde57-5121-49a7-a2e0-5f6fc871b7a6">
 
-<a name="why-doesn't-textual-support-ansi-themes"></a>
 ## Why doesn't Textual support ANSI themes?
 
 Textual will not generate escape sequences for the 16 themeable *ANSI* colors.
@@ -296,7 +278,6 @@ Textual has a design system which guarantees apps will be readable on all platfo
 
 There is currently a light and dark version of the design system, but more are planned. It will also be possible for users to customize the source colors on a per-app or per-system basis. This means that in the future you will be able to modify the core colors to blend in with your chosen terminal theme.
 
-<a name="why-doesn't-the-`datatable`-scroll-programmatically"></a>
 ## Why doesn't the `DataTable` scroll programmatically?
 
 If scrolling in your `DataTable` is _apparently_ broken, it may be because your `DataTable` is using the default value of `height: auto`.

faq.yml

@@ -1,7 +1,7 @@
 # FAQtory settings
 
-faq_url: "https://github.com/textualize/textual/blob/main/FAQ.md" # Replace this with the URL to your FAQ.md!
+faq_url: "https://textual.textualize.io/FAQ/" # 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 
+output_path: "./docs/FAQ.md" # Where FAQ.md should be generated
 templates_path: ".faq" # Path to templates

mkdocs-nav.yml

@@ -200,6 +200,7 @@ nav:
               - "how-to/index.md"
               - "how-to/center-things.md"
               - "how-to/design-a-layout.md"
+      - "FAQ.md"
       - "roadmap.md"
       - "Blog":
               - blog/index.md