mirror of
https://github.com/Textualize/textual.git
synced 2025-10-17 02:38:12 +03:00
Merge pull request #1726 from davep/package-docs
Allow for web vs local documentation building, with an eye on downstream packaging support
This commit is contained in:
Dave Pearson
3
.gitignore
vendored
3
.gitignore
vendored
@@ -110,6 +110,9 @@ venv.bak/
|
||||
|
||||
# mkdocs documentation
|
||||
/site
|
||||
/docs-offline
|
||||
/mkdocs-nav-online.yml
|
||||
/mkdocs-nav-offline.yml
|
||||
|
||||
# mypy
|
||||
.mypy_cache/
|
||||
|
||||
76
Makefile
76
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
|
||||
docs-serve:
|
||||
$(run) black --check src
|
||||
|
||||
.PHONY: clean-screenshot-cache
|
||||
clean-screenshot-cache:
|
||||
rm -rf .screenshot_cache
|
||||
mkdocs serve
|
||||
docs-build:
|
||||
mkdocs build
|
||||
docs-deploy:
|
||||
rm -rf .screenshot_cache
|
||||
mkdocs gh-deploy
|
||||
|
||||
.PHONY: docs-offline-nav
|
||||
docs-offline-nav:
|
||||
echo "INHERIT: mkdocs-offline.yml" > mkdocs-nav-offline.yml
|
||||
grep -v "\- \"*[Bb]log" mkdocs-nav.yml >> mkdocs-nav-offline.yml
|
||||
|
||||
.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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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"}
|
||||
```
|
||||
|
||||
|
||||
100
mkdocs-common.yml
Normal file
100
mkdocs-common.yml
Normal file
@@ -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
|
||||
@@ -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
|
||||
11
mkdocs-offline.yml
Normal file
11
mkdocs-offline.yml
Normal file
@@ -0,0 +1,11 @@
|
||||
INHERIT: mkdocs-common.yml
|
||||
|
||||
plugins:
|
||||
offline:
|
||||
privacy:
|
||||
exclude:
|
||||
glob:
|
||||
- "**/_template.md"
|
||||
- blog/*
|
||||
|
||||
site_dir: docs-offline
|
||||
16
mkdocs-online.yml
Normal file
16
mkdocs-online.yml
Normal file
@@ -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
|
||||
2374
poetry.lock
generated
2374
poetry.lock
generated
File diff suppressed because it is too large
Load Diff
@@ -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"
|
||||
|
||||
Reference in New Issue
Block a user