From b7bfc38a85c21d7a74bf69d05a8788b9bb8f6a18 Mon Sep 17 00:00:00 2001
From: Wesley B <62723358+wesleyboar@users.noreply.github.com>
Date: Fri, 5 Dec 2025 17:30:01 -0600
Subject: [PATCH 1/2] docs: clarify client vs theme test commands
---
docs/test.md | 78 ++++++++++++++++++++++++++++++++++++++++++----------
1 file changed, 63 insertions(+), 15 deletions(-)
diff --git a/docs/test.md b/docs/test.md
index 81c0b39..7b4d34d 100644
--- a/docs/test.md
+++ b/docs/test.md
@@ -4,9 +4,9 @@
## Test Locally
-You can test `mkdocs-tacc` locally with [PIP](https://pip.pypa.io/) or [Poetry](https://python-poetry.org/).
+You can test `mkdocs-tacc` or `mkdocs-tacc` clients locally with [PIP](https://pip.pypa.io/) or [Poetry](https://python-poetry.org/).
-You can test `mkdocs-tacc` clients the same way; some also support [Docker](https://docs.docker.com/) and [Make](https://www.gnu.org/software/make/). \*
+Some clients also support [Docker](https://docs.docker.com/) and [Make](https://www.gnu.org/software/make/). \*
/// tab | PIP
@@ -19,6 +19,10 @@ You can test `mkdocs-tacc` clients the same way; some also support [Docker](http
1. To **install** dependencies and **serve** docs in isolation:
+ //// tab | Test `mkdocs-tacc` Repo
+
+ To test client instead, use **Test on Client Repo** tab.
+
```shell
python -m venv venv
source venv/bin/activate
@@ -26,7 +30,20 @@ You can test `mkdocs-tacc` clients the same way; some also support [Docker](http
mkdocs serve
```
- A `mkdocs-tacc` client may require `install` of additional or different dependencies. See its documentation.
+ ////
+ //// tab | Test on Client Repo
+ select: True
+
+ The client repo might required additional or different commands. Check its documentation.
+
+ ```shell
+ python -m venv venv
+ source venv/bin/activate
+ pip install -e "."
+ mkdocs serve
+ ```
+
+ ////
To **deactivate** environment: `deactivate`
@@ -45,12 +62,27 @@ To **remove** environment: `rm -rf venv`
1. To **install** dependencies and **serve** docs in isolation:
+ //// tab | Test `mkdocs-tacc` Repo
+
+ To test client instead, use **Test on Client Repo** tab.
+
```shell
poetry install --sync --extras "all"
poetry run mkdocs serve
```
- A `mkdocs-tacc` client may require `install` of additional or different dependencies. See its documentation.
+ ////
+ //// tab | Test on Client Repo
+ select: True
+
+ The client repo might required additional or different commands. Check its documentation.
+
+ ```shell
+ poetry install --sync
+ poetry run mkdocs serve
+ ```
+
+ ////
To **deactivate** environment: `exit`
@@ -69,12 +101,12 @@ To **remove** environment: `poetry env remove --all`
1. To **install** dependencies and **serve** docs in isolation:
+ The client repo might required additional or different commands. Check its documentation.
+
```shell
docker compose up
```
- A `mkdocs-tacc` client may rely on a different command. See its documentation.
-
To **deactivate** environment: `docker compose stop`
To **remove** environment: `docker compose down`
@@ -90,12 +122,12 @@ To **remove** environment: `docker compose down`
1. To **install** dependencies and **serve** docs in isolation:
+ The client repo might required additional or different commands. Check its documentation.
+
```shell
make start
```
- A `mkdocs-tacc` client may rely on a different command. See its documentation.
-
To **deactivate** environment: `Ctrl+C`
To **remove** environment: `make stop`
@@ -108,12 +140,29 @@ Some clients will offer automatic, remote build and deploy for testing.
## Test on Client
-### at Specific Revision
+### Test on Client Locally
+
+Use **Test Client Repo** tab as you follow [Test Locally](#test-locally) instructions.
+
+/// tab | Test `mkdocs-tacc` Repo
-To test changes end-to-end on client repository:
+Ignore this tab. **Read the other tab.**
+
+///
+/// tab | Test on Client Repo
+ select: True
+
+**Read this tab.** Ignore the other tab.
+
+///
+
+
+### Test Theme at Specific Revision
+
+To test a specific revision of `mkdocs-tacc` on a client repository:
0. Clone and/or enter client repository.
-1. Install the theme at a specific version —
+1. Install the theme at a specific revision (e.g. a version) —
/// tab | PIP
@@ -130,7 +179,7 @@ To test changes end-to-end on client repository:
///
- — or a specific branch –
+ — or a specific branch —
/// tab | PIP
@@ -149,9 +198,9 @@ To test changes end-to-end on client repository:
— or other revision.
-### in Real-Time
+### Test Theme in Real-Time
-To test changes real-time on client repository:
+To test `mkdocs-tacc` theme changes in real-time on a client repository:
0. Clone and/or enter client repository.
1. Install the theme in editable mode, e.g.
@@ -192,4 +241,3 @@ To test changes real-time on client repository:
////
///
-
From 3761ce9342fe555bcc1c7023e615921d457d4173 Mon Sep 17 00:00:00 2001
From: Wesley B <62723358+wesleyboar@users.noreply.github.com>
Date: Fri, 5 Dec 2025 17:30:12 -0600
Subject: [PATCH 2/2] docs: clarify client vs theme test commands CONT
---
docs/test.md | 16 +++++++++++-----
1 file changed, 11 insertions(+), 5 deletions(-)
diff --git a/docs/test.md b/docs/test.md
index 7b4d34d..301167a 100644
--- a/docs/test.md
+++ b/docs/test.md
@@ -142,18 +142,22 @@ Some clients will offer automatic, remote build and deploy for testing.
### Test on Client Locally
-Use **Test Client Repo** tab as you follow [Test Locally](#test-locally) instructions.
+/// note |
-/// tab | Test `mkdocs-tacc` Repo
+As you follow [**Test Locally**](#test-locally) instructions, use **Test Client Repo** tab.
+
+//// tab | Test `mkdocs-tacc` Repo
Ignore this tab. **Read the other tab.**
-///
-/// tab | Test on Client Repo
+////
+//// tab | Test on Client Repo
select: True
**Read this tab.** Ignore the other tab.
+////
+
///
@@ -213,7 +217,9 @@ To test `mkdocs-tacc` theme changes in real-time on a client repository:
Where `../mkdocs-tacc` is the path to your clone of this repository.
- //// tip | If changes since that command are not reflected, try:
+ //// tip |
+
+ If changes since that command are not reflected, try:
```shell
pip uninstall mkdocs-tacc