Merge pull request #1726 from davep/package-docs

Allow for web vs local documentation building, with an eye on downstream packaging support

.gitignore

@@ -110,6 +110,9 @@ venv.bak/
 
 # mkdocs documentation
 /site
+/docs-offline
+/mkdocs-nav-online.yml
+/mkdocs-nav-offline.yml
 
 # mypy
 .mypy_cache/

Makefile

@@ -1,20 +1,70 @@
+run := poetry run
+
+.PHONY: test
 test:
-	pytest --cov-report term-missing --cov=textual tests/ -vv
+	$(run) pytest --cov-report term-missing --cov=textual tests/ -vv
+
+.PHONY: unit-test
 unit-test:
-	pytest --cov-report term-missing --cov=textual tests/ -vv -m "not integration_test"
+	$(run) pytest --cov-report term-missing --cov=textual tests/ -vv -m "not integration_test"
+
+.PHONY: test-snapshot-update
 test-snapshot-update:
-	pytest --cov-report term-missing --cov=textual tests/ -vv --snapshot-update
+	$(run) pytest --cov-report term-missing --cov=textual tests/ -vv --snapshot-update
+
+.PHONY: typecheck
 typecheck:
-	mypy src/textual
+	$(run) mypy src/textual
+
+.PHONY: format
 format:
-	black src
+	$(run) black src
+
+.PHONY: format-check
 format-check:
-	black --check src
+	$(run) black --check src
-docs-serve:
+
+.PHONY: clean-screenshot-cache
+clean-screenshot-cache:
 	rm -rf .screenshot_cache
-	mkdocs serve
+
-docs-build:
+.PHONY: docs-offline-nav
-	mkdocs build
+docs-offline-nav:
-docs-deploy:
+	echo "INHERIT: mkdocs-offline.yml" > mkdocs-nav-offline.yml
-	rm -rf .screenshot_cache
+	grep -v "\- \"*[Bb]log" mkdocs-nav.yml >> mkdocs-nav-offline.yml
-	mkdocs gh-deploy
+
+.PHONY: docs-online-nav
+docs-online-nav:
+	echo "INHERIT: mkdocs-online.yml" > mkdocs-nav-online.yml
+	cat mkdocs-nav.yml >> mkdocs-nav-online.yml
+
+.PHONY: docs-serve
+docs-serve: clean-screenshot-cache docs-online-nav
+	$(run) mkdocs serve --config-file mkdocs-nav-online.yml
+	rm -f mkdocs-nav-online.yml
+
+.PHONY: docs-build
+docs-build: docs-online-nav
+	$(run) mkdocs build --config-file mkdocs-nav-online.yml
+	rm -f mkdocs-nav-online.yml
+
+.PHONY: docs-build-offline
+docs-build-offline: docs-offline-nav
+	$(run) mkdocs build --config-file mkdocs-nav-offline.yml
+	rm -f mkdocs-nav-offline.yml
+
+.PHONY: clean-offline-docs
+clean-offline-docs:
+	rm -rf docs-offline
+
+.PHONY: docs-deploy
+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: build
+build: docs-build-offline
+	poetry build
+
+.PHONY: clean
+clean: clean-screenshot-cache clean-offline-docs

docs/guide/events.md

@@ -183,7 +183,7 @@ Let's look at an example which looks up word definitions from an [api](https://d
 
 === "Output"
 
-    ```{.textual path="docs/examples/events/dictionary.py" press="t,e,x,t,_,_,_,_,_,_,_,_,_,_,_"}
+    ```{.textual path="docs/examples/events/dictionary.py"}
     ```
 
 Note the highlighted line in the above code which calls `asyncio.create_task` to run a coroutine in the background. Without this you would find typing in to the text box to be unresponsive.

docs/index.md

@@ -81,10 +81,6 @@ Build sophisticated user interfaces with a simple Python API. Run your apps in t
 ```
 
 
-```{.textual path="docs/examples/events/dictionary.py" columns="100" lines="30" press="tab,_,t,e,x,t,_,_,_,_,_,_,_,_,_,_,_,_,_,_,_,_"}
-```
-
-
 ```{.textual path="docs/examples/guide/layout/combining_layouts.py" columns="100", lines="30"}
 ```
 

mkdocs-common.yml

@@ -0,0 +1,100 @@
+site_name: Textual
+
+markdown_extensions:
+  - attr_list
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+  - md_in_html
+  - admonition
+  - def_list
+  - meta
+
+  - toc:
+      permalink: true
+      baselevel: 1
+  - pymdownx.keys
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.superfences:
+      custom_fences:
+        - name: textual
+          class: textual
+          format: !!python/name:textual._doc.format_svg
+        - name: rich
+          class: rich
+          format: !!python/name:textual._doc.rich
+  - pymdownx.inlinehilite
+  - pymdownx.superfences
+  - pymdownx.snippets
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.snippets
+  - markdown.extensions.attr_list
+
+theme:
+  name: material
+  custom_dir: docs/custom_theme
+  features:
+    - navigation.tabs
+    - navigation.indexes
+    - navigation.tabs.sticky
+    - navigation.footer
+    - content.code.annotate
+    - content.code.copy
+  palette:
+  - media: "(prefers-color-scheme: light)"
+    scheme: default
+    accent: purple
+    toggle:
+      icon: material/weather-sunny
+      name: Switch to dark mode
+  - media: "(prefers-color-scheme: dark)"
+    scheme: slate
+    primary: black
+    toggle:
+      icon: material/weather-night
+      name: Switch to light mode
+
+plugins:
+  search:
+  autorefs:
+  mkdocstrings:
+    custom_templates: docs/_templates
+    default_handler: python
+    handlers:
+      python:
+        options:
+          show_root_heading: true
+          show_root_full_path: false
+          show_source: false
+          filters:
+            - "!^_"
+            - "^__init__$"
+            - "!^can_replace$"
+    watch:
+      - src/textual
+  exclude:
+    glob:
+      - "**/_template.md"
+
+
+extra_css:
+  - stylesheets/custom.css
+
+
+extra:
+  social:
+    - icon: fontawesome/brands/twitter
+      link: https://twitter.com/textualizeio
+      name: textualizeio on Twitter
+    - icon: fontawesome/brands/github
+      link: https://github.com/textualize/textual/
+      name: Textual on Github
+    - icon: fontawesome/brands/discord
+      link: https://discord.gg/Enf6Z3qhVr
+      name: Textual Discord server
+copyright: Copyright © Textualize, Inc

mkdocs-nav.yml

@@ -1,8 +1,3 @@
-site_name: Textual
-site_url: https://textual.textualize.io/
-repo_url: https://github.com/textualize/textual/
-edit_uri: edit/main/docs/
-
 nav:
   - Introduction:
     - "index.md"
@@ -178,114 +173,3 @@ nav:
     - "api/widget.md"
   - "Blog":
     - blog/index.md
-
-
-
-markdown_extensions:
-  - attr_list
-  - pymdownx.emoji:
-      emoji_index: !!python/name:materialx.emoji.twemoji
-      emoji_generator: !!python/name:materialx.emoji.to_svg
-  - md_in_html
-  - admonition
-  - def_list
-  - meta
-
-  - toc:
-      permalink: true
-      baselevel: 1
-  - pymdownx.keys
-  - pymdownx.tasklist:
-      custom_checkbox: true
-  - pymdownx.highlight:
-      anchor_linenums: true
-  - pymdownx.inlinehilite
-  - pymdownx.superfences:
-      custom_fences:
-        - name: textual
-          class: textual
-          format: !!python/name:textual._doc.format_svg
-        - name: rich
-          class: rich
-          format: !!python/name:textual._doc.rich
-  - pymdownx.inlinehilite
-  - pymdownx.superfences
-  - pymdownx.snippets
-  - pymdownx.tabbed:
-      alternate_style: true
-  - pymdownx.snippets
-  - markdown.extensions.attr_list
-
-theme:
-  name: material
-  custom_dir: docs/custom_theme
-  features:
-    - navigation.tabs
-    - navigation.indexes
-    - navigation.tabs.sticky
-    - navigation.footer
-    - content.code.annotate
-    - content.code.copy
-  palette:
-  - media: "(prefers-color-scheme: light)"
-    scheme: default
-    accent: purple
-    toggle:
-      icon: material/weather-sunny
-      name: Switch to dark mode
-  - media: "(prefers-color-scheme: dark)"
-    scheme: slate
-    primary: black
-    toggle:
-      icon: material/weather-night
-      name: Switch to light mode
-
-plugins:
-
-- blog:
-- rss:
-    match_path: blog/posts/.*
-    date_from_meta:
-      as_creation: date
-    categories:
-      - categories
-      - release
-      - tags
-- search:
-- autorefs:
-- mkdocstrings:
-    custom_templates: docs/_templates
-    default_handler: python
-    handlers:
-        python:
-          options:
-            show_root_heading: true
-            show_root_full_path: false
-            show_source: false
-            filters:
-              - "!^_"
-              - "^__init__$"
-              - "!^can_replace$"
-    watch:
-      - src/textual
-- exclude:
-    glob:
-      - "**/_template.md"
-
-
-extra_css:
-  - stylesheets/custom.css
-
-
-extra:
-  social:
-    - icon: fontawesome/brands/twitter
-      link: https://twitter.com/textualizeio
-      name: textualizeio on Twitter
-    - icon: fontawesome/brands/github
-      link: https://github.com/textualize/textual/
-      name: Textual on Github
-    - icon: fontawesome/brands/discord
-      link: https://discord.gg/Enf6Z3qhVr
-      name: Textual Discord server
-copyright: Copyright © Textualize, Inc

mkdocs-offline.yml

@@ -0,0 +1,11 @@
+INHERIT: mkdocs-common.yml
+
+plugins:
+  offline:
+  privacy:
+  exclude:
+    glob:
+      - "**/_template.md"
+      - blog/*
+
+site_dir: docs-offline

mkdocs-online.yml

@@ -0,0 +1,16 @@
+INHERIT: mkdocs-common.yml
+
+repo_url: https://github.com/textualize/textual/
+site_url: https://textual.textualize.io/
+edit_uri: edit/main/docs/
+
+plugins:
+  blog:
+  rss:
+    match_path: blog/posts/.*
+    date_from_meta:
+      as_creation: date
+    categories:
+      - categories
+      - release
+      - tags

pyproject.toml

@@ -24,7 +24,13 @@ classifiers = [
 include = [
     "src/textual/py.typed",
     { path = "docs/examples", format = "sdist" },
-    { path = "tests", format = "sdist" }
+    { path = "tests", format = "sdist" },
+    # The reason for the slightly convoluted path specification here is that
+    # poetry populates the exclude list with the content of .gitignore, and
+    # it also seems like exclude trumps include. So here we specify that we
+    # want to package up the content of the docs-offline directory in a way
+    # that works around that.
+    { path = "docs-offline/**/*", format = "sdist" }
 ]
 
 [tool.poetry.scripts]
@@ -54,7 +60,7 @@ mypy = "^1.0.0"
 pytest-cov = "^2.12.1"
 mkdocs = "^1.3.0"
 mkdocstrings = {extras = ["python"], version = "^0.20.0"}
-mkdocs-material = "^8.2.15"
+mkdocs-material = "^9.0.11"
 pre-commit = "^2.13.0"
 pytest-aiohttp = "^1.0.4"
 time-machine = "^2.6.0"