diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ebb8a1f..8591001 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,24 +4,28 @@ We are glad you are reading this. We welcome your contribution. Here are some important resources: -* [Known Issues](https://github.com/TACC/mkdocs-tacc/issues) -* [Active Proposals](https://github.com/TACC/mkdocs-tacc/pulls) -* [How to Test](./TESTING.md) +* [Known Issues][issues] +* [Active Proposals][proposals] +* [How to Test][test] ## Step by Step -1. [Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) this repository.\ +1. [Fork][fork] this repository.\ (unless you are a direct collaborator) -2. [Edit](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files) relevant files that need update.\ +2. [Edit][edit] relevant files that need update.\ ([upload images](https://docs.github.com/en/repositories/working-with-files/managing-files/adding-a-file-to-a-repository) as necessary) -4. [Commit](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits) your changes.\ +4. [Commit][commit] your changes.\ (write [clear commit messages](#writing-commit-messages)) -5. [Test](./TESTING.md) your changes.\ +5. [Test][test] your changes.\ (if comfortable using a command prompt) -6. [Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) a review.\ +6. [Request][request] a review.\ (a.k.a. create a "Pull Request") -## Advanced +[issues]: https://github.com/TACC/mkdocs-tacc/issues +[proposals]: https://github.com/TACC/mkdocs-tacc/pulls +[test]: https://tacc.github.io/mkdocs-tacc/test/ -- [Developing](./DEVELOPING.md) -- [Publishing](./PUBLISHING.md) +[fork]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo +[edit]: https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files +[commit]: https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits +[request]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request diff --git a/DEVELOPING.md b/DEVELOPING.md deleted file mode 100644 index b7b1396..0000000 --- a/DEVELOPING.md +++ /dev/null @@ -1,36 +0,0 @@ -# How to Develop - -> [!NOTE] -> This project uses [Poetry] (v2) for dependency management. - -[Poetry]: https://python-poetry.org/ - -- [Quick Start](#quick-start) -- [Testing](#testing) - -## Quick Start - -Clone this repository, install all dependencies, activate virtual environment, serve the documentation, e.g. - -```shell -git clone https://github.com/TACC/mkdocs-tacc.git -cd mkdocs-tacc -poetry install --sync --all-extras -poetry run mkdocs serve -``` - -> [!NOTE] -> If you don't have Poetry installed, you may use `pip`, but we offer no peer support for this approach: -> -> ```shell -> git clone https://github.com/TACC/mkdocs-tacc.git -> cd mkdocs-tacc -> python -m venv venv -> source venv/bin/activate # On Windows, use: venv\Scripts\activate -> pip install -e . -> pip install mkdocs -> mkdocs serve -> ``` - -> [!TIP] -> To test changes to this theme on a client repository, follow [`TESTING.md` "Test on Client"](./TESTING.md#test-on-client). diff --git a/TESTING.md b/TESTING.md deleted file mode 100644 index c99cbbb..0000000 --- a/TESTING.md +++ /dev/null @@ -1,51 +0,0 @@ -## How to Test - -> [!NOTE] -> Testing is manual and requires using a command prompt. - -1. Follow [`DEVELOPING.md` "Quick Start"](./DEVELOPING.md#quick-start). -2. Checkout your branch e.g. - ```shell - git checkout __THE_NAME_OF_YOUR_BRANCH__ - ``` -3. Make changes. -4. If you changed theme files: - 1. Stop the server (e.g. `Ctrl+C`). - 2. Serve the docs again: - ```shell - poetry run mkdocs serve - ``` - -## Test on Client - -### End-to-End - -To test changes end-to-end on client repository: - -0. Clone and/or enter client repository. -1. Install the theme at a specific revision, e.g. - - ```shell - poetry add git+https://github.com/TACC/mkdocs-tacc.git#main - ``` - -### Real-Time - -To test changes real-time on client repository: - -0. Clone and/or enter client repository. -1. Install the theme in editable mode, e.g. - - ```shell - poetry add --editable ../mkdocs-tacc # ¹ - ``` - -¹ Where `../mkdocs-tacc` is the path to your clone of this repository. - -> [!TIP] -> If changes since that command are not reflected, try: -> -> ```shell -> poetry remove mkdocs-tacc -> poetry add --editable ../mkdocs-tacc # ¹ -> ``` diff --git a/docs/assets/extra.css b/docs/assets/extra.css new file mode 100644 index 0000000..d223b53 --- /dev/null +++ b/docs/assets/extra.css @@ -0,0 +1,15 @@ +/* to hide first level of TOC */ +.toc > ul { + padding-left: 0; +} +.toc > ul > li { + list-style: none; +} +.toc > ul > li > a { + display: none; +} + +/* to emphasize second level of TOC */ +.toc > ul > li > ul > li > a { + font-weight: var(--bold); +} diff --git a/docs/test.md b/docs/test.md new file mode 100644 index 0000000..8710755 --- /dev/null +++ b/docs/test.md @@ -0,0 +1,186 @@ +# How to Test + +[TOC] + +## 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` clients the same way; some also support [Docker](https://docs.docker.com/) and [Make](https://www.gnu.org/software/make/). \* + +/// tab | PIP + +0. Ensure PIP is **updated**; `21.3+` recommended: + + ```shell + pip install --upgrade pip + ``` + +1. To **install** dependencies and **serve** docs in isolation: + + ```shell + python -m venv venv + source venv/bin/activate + pip install -e . + mkdocs serve + ``` + +To **deactivate** environment: `deactivate` + +To **remove** environment: `rm -rf venv` + +/// +/// tab | Poetry + +0. Ensure Poetry is **updated**; `1.5.0+` recommended: + + ```shell + poetry self update + ``` + +1. To **install** dependencies and **serve** docs in isolation: + + ```shell + poetry install --sync + poetry run mkdocs serve + ``` + +To **deactivate** environment: `exit` + +To **remove** environment: `poetry env remove --all` + +/// +/// tab | \* Docker + +0. Ensure Docker is **updated**; `20.10.0+` recommended: + + ```shell + docker --version + ``` + + Only checks version. Upgrade differs per platform. + +1. To **install** dependencies and **serve** docs in isolation: + + ```shell + docker compose up + ``` + +To **deactivate** environment: `docker compose stop` + +To **remove** environment: `docker compose down` + +/// +/// tab | \* Make + +0. Ensure Make is **available**: + + ```shell + make --version + ``` + + Only checks version. Upgrade differs per platform. + +1. To **install** dependencies and **serve** docs in isolation: + + ```shell + make start + ``` + +To **deactivate** environment: `Ctrl+C` + +To **remove** environment: `make stop` + +/// + +## Test Remotely + +Some clients will offer automatic, remote build and deploy for testing. + +## Test on Client + +### at Specific Revision + +To test changes end-to-end on client repository: + +0. Clone and/or enter client repository. +1. Install the theme at a specific version — + + /// tab | PIP + + ```shell + pip install mkdocs-tacc==0.5.0 + ``` + + /// + /// tab | Poetry + + ```shell + poetry add mkdocs-tacc@0.5.0 + ``` + + /// + + — or a specific branch – + + /// tab | PIP + + ```shell + pip install git+https://github.com/TACC/mkdocs-tacc.git#work-in-progress + ``` + + /// + /// tab | Poetry + + ```shell + poetry add git+https://github.com/TACC/mkdocs-tacc.git#work-in-progress + ``` + + /// + + — or other revision. + +### in Real-Time + +To test changes real-time on client repository: + +0. Clone and/or enter client repository. +1. Install the theme in editable mode, e.g. + + /// tab | PIP + + ```shell + pip install -e ../mkdocs-tacc + ``` + + Where `../mkdocs-tacc` is the path to your clone of this repository. + + //// tip | If changes since that command are not reflected, try: + + ```shell + pip uninstall mkdocs-tacc + pip install -e ../mkdocs-tacc + ``` + + //// + + /// + /// tab | Poetry + + ```shell + poetry add --editable ../mkdocs-tacc + ``` + + Where `../mkdocs-tacc` is the path to your clone of this repository. + + //// tip | If changes since that command are not reflected, try: + + ```shell + poetry remove mkdocs-tacc + poetry add --editable ../mkdocs-tacc # ¹ + ``` + + //// + + /// + diff --git a/mkdocs.yml b/mkdocs.yml index 08a3260..79ea18d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -17,12 +17,16 @@ theme: portal_url: https://github.com/TACC/mkdocs-tacc portal_name: TACC/mkdocs-tacc +extra_css: + - assets/extra.css + nav: - Getting Started: - Quick Start: index.md - Configuration: configure.md - Customization: customize.md - Extensions: extensions.md + - Testing: test.md - Examples: - Basic: clients/basic-example.md - TACC Docs: clients/tacc-docs-example.md diff --git a/mkdocs_tacc/tacc_readthedocs/css/tacc-theme/readthedocs-reskin.css b/mkdocs_tacc/tacc_readthedocs/css/tacc-theme/readthedocs-reskin.css index 3c413ef..cf46882 100644 --- a/mkdocs_tacc/tacc_readthedocs/css/tacc-theme/readthedocs-reskin.css +++ b/mkdocs_tacc/tacc_readthedocs/css/tacc-theme/readthedocs-reskin.css @@ -262,11 +262,6 @@ svg.logo [fill]:not([fill="none"]) { content: unset; } -/* to hide the
from ReadTheDocs theme markup */ -.rst-content [role="navigation"] hr { - display: none; -} - /* to hide the ≫ from ReadTheDocs theme markup */ .rst-content [role="navigation"] li::before { margin-left: -1.25ch; diff --git a/mkdocs_tacc/tacc_readthedocs/footer.html b/mkdocs_tacc/tacc_readthedocs/footer.html index 17b15a7..6574539 100644 --- a/mkdocs_tacc/tacc_readthedocs/footer.html +++ b/mkdocs_tacc/tacc_readthedocs/footer.html @@ -2,7 +2,7 @@ {# All changes must start and end with comments " TACC: " and " /TACC " #}