From cb3f055401e69d647535888c09fce358b9708ea4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89douard=20Lopez?= Date: Thu, 18 Jan 2024 23:35:58 +0100 Subject: [PATCH 1/5] docs: basic mkdocs workflow --- docker/doc.Dockerfile | 17 ++++ docs/components/hero-banner.md | 6 ++ docs/index.md | 172 +++++++++++++++++++++++++++++++++ makefile | 25 ++++- mkdocs.yml | 73 ++++++++++++++ 5 files changed, 291 insertions(+), 2 deletions(-) create mode 100644 docker/doc.Dockerfile create mode 100644 docs/components/hero-banner.md create mode 100644 docs/index.md create mode 100644 mkdocs.yml diff --git a/docker/doc.Dockerfile b/docker/doc.Dockerfile new file mode 100644 index 00000000..df9b50e3 --- /dev/null +++ b/docker/doc.Dockerfile @@ -0,0 +1,17 @@ +FROM python:3 + +# Create app directory +WORKDIR /usr/src/app + +RUN pip install \ + mkdocs \ + mkdocs-pdf-export-plugin \ + mkdocs-material + +COPY . . + +# RUN mkdocs build + +EXPOSE 8000 +# CMD ["python", "-m", "http.server", "8000", "-d", "./site"] +CMD ["mkdocs" "serve" "--clean"] diff --git a/docs/components/hero-banner.md b/docs/components/hero-banner.md new file mode 100644 index 00000000..dffe659f --- /dev/null +++ b/docs/components/hero-banner.md @@ -0,0 +1,6 @@ +> Pretty, minimal and fast Fish 🐟 prompt, ported from [`zsh`](https://github.com/sindresorhus/pure). + +
+ Pure with dark colorscheme + Pure with light colorscheme +
diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..874e827e --- /dev/null +++ b/docs/index.md @@ -0,0 +1,172 @@ +
+ +
+ +[![ci-status]][ci-link] ![fish-3] [![release-version]][release-link] [![sponsors]][sponsor-link] + +
+ +# pure + +{% include 'components/hero-banner.md' %} + +## :rocket: Install + +**:warning: requirements**: fish `≥3.x` + +### [Fisher](https://github.com/jorgebucaran/fisher) + +```shell +fisher install pure-fish/pure +``` + +### Manually + +Via [cURL](https://curl.haxx.se): + +```shell +# Download the installer to `/tmp` +curl git.io/pure-fish --output /tmp/pure_installer.fish --location --silent +# Source and trigger the installer +source /tmp/pure_installer.fish; and install_pure +``` + +## Features + +Fully **customizable** (colors, symbols and features): + +* Excellent prompt character `❯` : + * Change `❯` to red when previous command has failed ; + * Start prompt with _current working directory_ 🏴 ; + * Compact-mode (single-line prompt) 🏴 ; +* Display _current folder_ tail ; +* check for new release on start 🏴 ; +* Display _username_ and _hostname_ when in an `SSH` session ; +* Display command _duration_ when longer than `5` seconds ; +* Display `Python` _virtualenv_ when activated 🏴 ; +* Display `VI` mode and custom symbol for non-insert mode 🏴 ; +* Display `kubernetes` context and namespace +* Display container indicator (e.g. `docker`, `podman`, `LXC`/`LXD`) 🏴 +* Show system time 🏴 ; +* Show number of running jobs 🏴 ; +* Prefix when `root` 🏴 ; +* Display `git` branch name 🏴 ; + * Display `*` when `git` repository is _dirty_ ; + * Display `≡` when `git` repository is _stashed_ ; + * Display `⇡` when branch is _ahead_ (commits to push) ; + * Display `⇣` when branch is _behind_ (commits to pull) ; + * Async update when [configured with fish-async-prompt](https://github.com/pure-fish/pure/wiki/Async-git-Prompt) ; +* Update terminal title with _current folder_ and _command_ ; +* Detect when running in a container ; +* Shorten _current folder_ component 🏴; + +🏴: Enabled or disabled via a [feature flag](#-features-flags). + +## :paintbrush: Configuration + +You can tweak `pure` behavior and color by changing [universal variables](https://fishshell.com/docs/current/tutorial.html#tut_universal) either directly in the terminal or in your `config.fish`, _e.g._: + +```shell +set --universal pure_show_system_time true +set --universal pure_color_system_time pure_color_mute +``` + +### Prompt Symbol + +| Option | Default | Description | +| :------------------------------------- | :------ | :--------------------------------------------------------------------------- | +| **`pure_symbol_container_prefix`** | | Prefix when being inside a container ([to customize][to-set]) | +| **`pure_symbol_git_dirty`** | `*` | Repository is Dirty (uncommitted/untracked changes). | +| **`pure_symbol_git_stash`** | `≡` | Repository git stash status. | +| **`pure_symbol_git_unpulled_commits`** | `⇣` | Branch is behind upstream (commits to pull). | +| **`pure_symbol_git_unpushed_commits`** | `⇡` | Branch is ahead upstream (commits to push). | +| **`pure_symbol_k8s_prefix`** | `☸` | Prefix when being connected to Kubernetes/K8s | +| **`pure_symbol_prefix_root_prompt`** | `#` | Prefix prompt when logged in as `root`. | +| **`pure_symbol_prompt`** | `❯` | Prompt symbol. | +| **`pure_symbol_reverse_prompt`** | `❮` | VI non-insert mode symbol. | +| **`pure_symbol_ssh_prefix`** | | Prefix when being connected to SSH session (default: [undefined][to-set]) | +| **`pure_symbol_title_bar_separator`** | `-` | Separator in terminal's windows title. | +| **`pure_symbol_virtualenv_prefix`** | | Prefix when a Python virtual env is activated (default: [undefined][to-set]) | + +> :information_source: Need [safer `git` symbols](https://github.com/sindresorhus/pure/wiki/Customizations,-hacks-and-tweaks#safer-symbols)? + +### 🔌 Features' Flags + +| Option | Default | Description | +| :------------------------------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **`pure_begin_prompt_with_current_directory`** | `true` | `true`: _`pwd` `git`, `SSH`, duration_.
`false`: _`SSH` `pwd` `git`, duration_. | +| **`pure_check_for_new_release`** | `false` | `true`: check repo for new release (on every shell start) | +| **`pure_enable_container_detection`** | `true` | `false`: Do not check if run in container (e.g. `docker`, `podman`, `LXC`/`LXD`, etc.).
:warning: Detection is a bit [tricky across OSes][container-detection]. | +| **`pure_enable_git`** | `true` | Show info about Git repository. | +| **`pure_enable_k8s`** | `false` | `true`: shows `kubernetes` context and namespace. | +| **`pure_enable_single_line_prompt`** | `false` | `true`: Compact prompt as a single line | +| **`pure_enable_virtualenv`** | `true` | Show virtual env name (based on `VIRTUAL_ENV` or `CONDA_DEFAULT_ENV`). | +| **`pure_reverse_prompt_symbol_in_vimode`** | `true` | `true`: `❮` indicate a non-insert mode.
`false`: indicate vi mode with `[I]`, `[N]`, `[V]`. | +| **`pure_separate_prompt_on_error`** | `false` | Show last command [exit code as a separate character][exit-code]. | +| **`pure_shorten_prompt_current_directory_length`** | `0` | Shorten every prompt path component but the last to X characters (0 do not shorten) | +| **`pure_shorten_window_title_current_directory_length`** | `0` | Shorten every window title path component but the last to X characters (0 do not shorten) | +| **`pure_show_jobs`** | `false` | Show Number of running jobs | +| **`pure_show_prefix_root_prompt`** | `false` | `true`: shows prompt prefix when logged in as `root`. | +| **`pure_show_subsecond_command_duration`** | `false` | Show subsecond (ex. 1.5s) in command duration. | +| **`pure_show_system_time`** | `false` | `true`: shows system time before the prompt symbol (as `%H:%M:%S`). | +| **`pure_threshold_command_duration`** | `5` | Show command duration when above this value (seconds). | + +### 🎨 Colours + +> :information_source: See [`set_color`][fish-set-color] documentation for full possibilities. + +> :warning: The absence of `$` sign is expected in `pure_` named colours. + +| Base Color | Inherited by | Default | +| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------- | +| **`pure_color_danger`** | **`pure_color_prompt_on_error`** | `red` | +| **`pure_color_dark`** | | `black` | +| **`pure_color_info`** | **`pure_color_git_unpulled_commits`**
**`pure_color_git_unpushed_commits`** | `cyan` | +| **`pure_color_light`** | **`pure_color_username_root`** | `white` | +| **`pure_color_mute`** | **`pure_color_git_branch`**
**`pure_color_git_dirty`**
**`pure_color_git_stash`**
**`pure_color_hostname`**
**`pure_color_at_sign`**
**`pure_color_username_normal`**
**`pure_color_virtualenv`** | `brblack` | +| **`pure_color_normal`** | **`pure_color_jobs`** | `normal` | +| **`pure_color_primary`** | **`pure_color_current_directory`** | `blue` | +| **`pure_color_success`** | **`pure_color_prompt_on_success`** | `magenta` | +| **`pure_color_warning`** | **`pure_color_command_duration`** | `yellow` | + +## :+1: Contribute + +**requirements:** [`docker`](https://docs.docker.com/install/) (isolate from your environment), get familiar with [CONTRIBUTING.md][contributing] guidelines. + +Specify the [`FISH_VERSION`][fish-releases] you want, and the `CMD` executed by the container: + + make build-pure-on FISH_VERSION=3.3.1 + make dev-pure-on FISH_VERSION=3.3.1 CMD="fishtape tests/*.test.fish" + +## :man_technologist: Maintainer + +* [Édouard Lopez](https://github.com/edouard-lopez) + +## :clap: Thanks + +* [@andreiborisov](https://github.com/andreiborisov) for the [docker images][docker-images] ; +* [@jorgebucaran](https://github.com/jorgebucaran/) for [fishtape](https://github.com/jorgebucaran/fishtape) ; +* [@rafaelrinaldi](https://github.com/pure-fish/pure) for starting the project ; + +## :classical_building: License + +[MIT][MIT] + +[to-set]: #paintbrush-configuration +[ci-link]: "Github CI" +[ci-status]: https://img.shields.io/github/actions/workflow/status/pure-fish/pure/.github/workflows/ci.yml?style=flat-square + +[fish-3]: "Support Fish 3" +[exit-code]: "See pure-zsh wiki" +[fish-releases]: https://github.com/fish-shell/fish-shell/releases +[docker-images]: https://github.com/andreiborisov/docker-fish/ +[MIT]: LICENSE.md +[fish-set-color]: https://fishshell.com/docs/current/cmds/set_color.html +[container-detection]: https://stackoverflow.com/q/23513045/802365 + +[release-version]: https://img.shields.io/github/v/tag/pure-fish/pure?label=latest%20&style=flat-square +[release-link]: https://github.com/pure-fish/pure/releases "GitHub tag (latest SemVer)" +[sponsors]: https://img.shields.io/github/sponsors/edouard-lopez?label=💰&style=flat-square "GitHub Sponsors" +[sponsor-link]: https://github.com/sponsors/edouard-lopez/ "Become a sponsor" + +[contributing]: CONTRIBUTING.md diff --git a/makefile b/makefile index a4368e57..386232b5 100644 --- a/makefile +++ b/makefile @@ -22,7 +22,7 @@ build-pure-on: --target ${STAGE} \ --build-arg FISH_VERSION=${FISH_VERSION} \ --tag=pure-${STAGE}-${FISH_VERSION} \ - --load \ + --load \ ./ .PHONY: dev-pure-on @@ -66,7 +66,7 @@ build-pure-on-nix: --file ./docker/${STAGE}.Dockerfile \ --build-arg FISH_VERSION=${FISH_VERSION} \ --tag=pure-${STAGE}-${FISH_VERSION} \ - --load \ + --load \ ./ dev-pure-on-nix: STAGE?=nix @@ -87,3 +87,24 @@ dev-pure-on-nix: test-pure-on-nix: CMD?=fishtape tests/*.test.fish test-pure-on-nix: $(MAKE) dev-pure-on-nix CMD="${CMD}" TTY= + + +build-pure-doc: + docker build \ + --file ./docker/doc.Dockerfile \ + --tag=pure-doc \ + --load \ + ./ + +serve-pure-doc: + docker run \ + --name mkdocs \ + --tty \ + --interactive \ + --rm \ + --publish 8000:8000 \ + --env "DEV_ADDR=0.0.0.0:8000" \ + --env "LIVE_RELOAD_SUPPORT=true" \ + --env ADD_MODULES="mkdocs-material mkdocs-awesome-pages-plugin mkdocs-include-markdown-plugin" \ + --volume=$$(pwd):/mkdocs \ + polinux/mkdocs diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..52497b58 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,73 @@ +site_name: Pure.fish +site_description: " Pretty, minimal and fast Fish 🐟 prompt" +site_author: "Édouard Lopez" +docs_dir: docs/ +repo_name: "pure-fish/pure" +repo_url: "https://github.com/pure-fish/pure" +nav: + - Home: index.md +theme: + # name: "material" + name: "material" + include_sidebar: true + features: + - navigation.tabs + - navigation.tracking + - navigation.expand + - navigation.indexes + logo: spinak_iac.png + favicon: spinak_iac.png + icon: + repo: fontawesome/brands/gitlab + admonition: + note: octicons/tag-16 + abstract: octicons/checklist-16 + info: octicons/info-16 + tip: octicons/squirrel-16 + success: octicons/check-16 + question: octicons/question-16 + warning: octicons/alert-16 + failure: octicons/x-circle-16 + danger: octicons/zap-16 + bug: octicons/bug-16 + example: octicons/beaker-16 + quote: octicons/quote-16 + palette: + - scheme: default + primary: teal + accent: teal + toggle: + icon: material/toggle-switch-off-outline + name: Switch to dark mode + - scheme: slate + primary: teal + accent: teal + toggle: + icon: material/toggle-switch + name: Switch to light mode + font: + text: Open Sans + code: Roboto Mono + +markdown_extensions: + - admonition + # - attr_list + # - md_in_html + # - pymdownx.details + # - pymdownx.superfences + # - pymdownx.tabbed: + # alternate_style: true + # - pymdownx.highlight + # - pymdownx.inlinehilite + # - pymdownx.snippets + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg + # - toc: + # permalink: true + + +plugins: + # - search + - awesome-pages + - include-markdown From 556ae61e94b91daf6aaeb7f6187b30eadacd5d21 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89douard=20Lopez?= Date: Fri, 19 Jan 2024 01:08:48 +0100 Subject: [PATCH 2/5] docs: continue migration fixes #339 --- CODE_OF_CONDUCT.md | 4 + CONTRIBUTING.md | 25 +++-- docs/.pages | 4 + RELEASE.md => docs/RELEASE.md | 17 +++- docs/about.md | 20 ++++ docs/components/.pages | 1 + docs/components/colours.md | 22 ++++ docs/components/configuration.md | 7 ++ docs/components/features-list.md | 104 +++++++++++++++++++ docs/components/features-overview.md | 30 ++++++ docs/components/installation.md | 21 ++++ docs/contributing.md | 5 + docs/index.md | 145 ++------------------------- makefile | 2 +- mkdocs.yml | 26 ++--- 15 files changed, 270 insertions(+), 163 deletions(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 docs/.pages rename RELEASE.md => docs/RELEASE.md (77%) create mode 100644 docs/about.md create mode 100644 docs/components/.pages create mode 100644 docs/components/colours.md create mode 100644 docs/components/configuration.md create mode 100644 docs/components/features-list.md create mode 100644 docs/components/features-overview.md create mode 100644 docs/components/installation.md create mode 100644 docs/contributing.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..fa849356 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,4 @@ +## Code of Conduct + +* Be kind to others ; +* Critic code not people. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4024dbef..47046f8a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,18 +1,23 @@ -# Contribution Guide +## :+1: Contribute -## Code of Conduct +!!! info -* Be kind to others ; -* Critic code not people. + We use [`docker`](https://docs.docker.com/install/) to isolate from our working environment. -## Release +Specify the [`FISH_VERSION`][fish-releases] you want, and the `CMD` executed by the container: -Note, we follow [semver](https://semver.org/), release is manage in the pipeline, see [RELEASE.md](./RELEASE.md) + make build-pure-on FISH_VERSION=3.3.1 + make dev-pure-on FISH_VERSION=3.3.1 CMD="fishtape tests/*.test.fish" -## Code Conventions for `pure` +## Code Conventions -* Use the idiomatic [`test` instead of `[`](httpsc://fishshell.com/docs/current/commands.html#test) brackets (as recommended by the documentation). -* Use **long form options**, _e.g._ `set --local`, as they are more explicit over cryptic 1-letter form. +### Be Fishy + +Use the idiomatic [`test` instead of `[`](httpsc://fishshell.com/docs/current/commands.html#test) brackets (as recommended by the documentation). + +### Be Explicit + +Use **long form options**, _e.g._ `set --local`, as they are more explicit over cryptic 1-letter form. ### Naming Public Item @@ -112,3 +117,5 @@ $pure_enable_git_async = false ```fish $pure_threshold_command_duration ``` + +[fish-releases]: https://github.com/fish-shell/fish-shell/releases diff --git a/docs/.pages b/docs/.pages new file mode 100644 index 00000000..8d573b3c --- /dev/null +++ b/docs/.pages @@ -0,0 +1,4 @@ +nav: + - Documentation: . + - Contributing: contributing + - About: about diff --git a/RELEASE.md b/docs/RELEASE.md similarity index 77% rename from RELEASE.md rename to docs/RELEASE.md index 12ce93e7..6e16db50 100644 --- a/RELEASE.md +++ b/docs/RELEASE.md @@ -1,8 +1,12 @@ -# Releasing +## Releasing Release process is automated in the pipeline with the following steps. -## Test +!!! info + + We follow [semver](https://semver.org/), release is manage in the pipeline + +### Test We run the test workflow on: @@ -13,9 +17,11 @@ We run the test workflow on: * `**.fish` files with the exception `conf.d/pure.fish`, as we have dedicated mechanism to manage versions bump ; * and workflow (`*.yml`) files -## Versioning +### Versioning + +!!! success -**required:** Commits must **[follow conventional commits convention][coco]**. + Commit messages must **[follow conventional commits convention][coco]**. Versioning is done automatically based on commit messages and triggered only on `master` branch. @@ -25,10 +31,11 @@ Details: 2. Then update `$pure_version` value in `./conf.d/pure.fish` ; 3. Finally commit and [push the change][push] to the repo. -## Adding new tag +### Adding new tag The `add-version-tag.yml` pipeline is triggered only for `master` when `./conf.d/pure.fish` is changed and add a tagged based on `$pure_version`. [next-version]: https://github.com/thenativeweb/get-next-version [push]: https://github.com/ad-m/github-push-action + [coco]: https://www.conventionalcommits.org/en/v1.0.0/ diff --git a/docs/about.md b/docs/about.md new file mode 100644 index 00000000..883925a7 --- /dev/null +++ b/docs/about.md @@ -0,0 +1,20 @@ +# About + +## :classical_building: License + +[MIT][MIT] + +## Contributors + +### :man_technologist: Maintainer + +* [Édouard Lopez](https://github.com/edouard-lopez) + +### :clap: Thanks + +* [@andreiborisov](https://github.com/andreiborisov) for the [docker images][docker-images] ; +* [@jorgebucaran](https://github.com/jorgebucaran/) for [fishtape](https://github.com/jorgebucaran/fishtape) ; +* [@rafaelrinaldi](https://github.com/pure-fish/pure) for starting the project ; + +[MIT]: ../LICENSE.md +[docker-images]: https://github.com/andreiborisov/docker-fish/ diff --git a/docs/components/.pages b/docs/components/.pages new file mode 100644 index 00000000..0dcafb34 --- /dev/null +++ b/docs/components/.pages @@ -0,0 +1 @@ +hide: true \ No newline at end of file diff --git a/docs/components/colours.md b/docs/components/colours.md new file mode 100644 index 00000000..54cda90e --- /dev/null +++ b/docs/components/colours.md @@ -0,0 +1,22 @@ +!!! tip + + See [`set_color`][fish-set-color] documentation for full possibilities. + +!!! info + + The absence of `$` sign is expected in `pure_` named colours. + +| Base Color | Inherited by | Default | +| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------- | +| **`pure_color_danger`** | **`pure_color_prompt_on_error`** | `red` | +| **`pure_color_dark`** | | `black` | +| **`pure_color_info`** | **`pure_color_git_unpulled_commits`**
**`pure_color_git_unpushed_commits`** | `cyan` | +| **`pure_color_light`** | **`pure_color_username_root`** | `white` | +| **`pure_color_mute`** | **`pure_color_git_branch`**
**`pure_color_git_dirty`**
**`pure_color_git_stash`**
**`pure_color_hostname`**
**`pure_color_at_sign`**
**`pure_color_username_normal`**
**`pure_color_virtualenv`** | `brblack` | +| **`pure_color_normal`** | **`pure_color_jobs`** | `normal` | +| **`pure_color_primary`** | **`pure_color_current_directory`** | `blue` | +| **`pure_color_success`** | **`pure_color_prompt_on_success`** | `magenta` | +| **`pure_color_warning`** | **`pure_color_command_duration`** | `yellow` | + + +[fish-set-color]: https://fishshell.com/docs/current/cmds/set_color.html diff --git a/docs/components/configuration.md b/docs/components/configuration.md new file mode 100644 index 00000000..dc2c03cd --- /dev/null +++ b/docs/components/configuration.md @@ -0,0 +1,7 @@ + +You can tweak `pure` behavior and color by changing [universal variables](https://fishshell.com/docs/current/tutorial.html#tut_universal) either directly in the terminal or in your `config.fish`, _e.g._: + +```shell +set --universal pure_show_system_time true +set --universal pure_color_system_time pure_color_mute +``` diff --git a/docs/components/features-list.md b/docs/components/features-list.md new file mode 100644 index 00000000..f9acceff --- /dev/null +++ b/docs/components/features-list.md @@ -0,0 +1,104 @@ +### Prompt Symbol + +| Option | Default | Description | +| :----------------------- | :------ | :------------- | +| **`pure_symbol_prompt`** | `❯` | Prompt symbol. | + +### Git + +| Option | Default | Description | +| :------------------------------------- | :------ | :--------------------------------------------------- | +| **`pure_enable_git`** | `true` | Show info about Git repository. | +| **`pure_symbol_git_dirty`** | `*` | Repository is Dirty (uncommitted/untracked changes). | +| **`pure_symbol_git_stash`** | `≡` | Repository git stash status. | +| **`pure_symbol_git_unpulled_commits`** | `⇣` | Branch is behind upstream (commits to pull). | +| **`pure_symbol_git_unpushed_commits`** | `⇡` | Branch is ahead upstream (commits to push). | + +> :information_source: Need [safer `git` symbols](https://github.com/sindresorhus/pure/wiki/Customizations,-hacks-and-tweaks#safer-symbols)? + +### Kubernetes + +| Option | Default | Description | +| :--------------------------- | :------ | :------------------------------------------------ | +| **`pure_symbol_k8s_prefix`** | `☸` | Prefix when being connected to Kubernetes/K8s | +| **`pure_enable_k8s`** | `false` | `true`: shows `kubernetes` context and namespace. | + +### VI Mode + +| Option | Default | Description | +| :----------------------------------------- | :------ | :---------------------------------------------------------------------------------------------- | +| **`pure_reverse_prompt_symbol_in_vimode`** | `true` | `true`: `❮` indicate a non-insert mode.
`false`: indicate vi mode with `[I]`, `[N]`, `[V]`. | +| **`pure_symbol_reverse_prompt`** | `❮` | VI non-insert mode symbol. | + +### Container Detection (Docker) + +| Option | Default | Description | +| :------------------------------------ | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **`pure_enable_container_detection`** | `true` | `false`: Do not check _pure_ runs inside a container (e.g. `docker`, `podman`, `LXC`/`LXD`, etc.).
:warning: Detection is a bit [tricky across OSes][container-detection]. | +| **`pure_symbol_container_prefix`** | | Prefix when being inside a container ([to customize][to-set]) | + +### Working as Root + +| Option | Default | Description | +| :----------------------------------- | :------ | :---------------------------------------------------- | +| **`pure_show_prefix_root_prompt`** | `false` | `true`: shows prompt prefix when logged in as `root`. | +| **`pure_symbol_prefix_root_prompt`** | `#` | Prefix prompt when logged in as `root`. | + +### SSH Session + +| Option | Default | Description | +| :--------------------------- | :------ | :------------------------------------------------------------------------ | +| **`pure_symbol_ssh_prefix`** | | Prefix when being connected to SSH session (default: [undefined][to-set]) | + +### Python Virtualenv + +| Option | Default | Description | +| :---------------------------------- | :------ | :--------------------------------------------------------------------------- | +| **`pure_enable_virtualenv`** | `true` | Show virtual env name (based on `VIRTUAL_ENV` or `CONDA_DEFAULT_ENV`). | +| **`pure_symbol_virtualenv_prefix`** | | Prefix when a Python virtual env is activated (default: [undefined][to-set]) | + +### Time & Duration + +| Option | Default | Description | +| :----------------------------------------- | :------ | :------------------------------------------------------------------ | +| **`pure_show_system_time`** | `false` | `true`: shows system time before the prompt symbol (as `%H:%M:%S`). | +| **`pure_show_subsecond_command_duration`** | `false` | Show subsecond (ex. 1.5s) in command duration. | +| **`pure_threshold_command_duration`** | `5` | Show command duration when above this value (seconds). | + +### Title + +| Option | Default | Description | +| :------------------------------------------------------- | :------ | :---------------------------------------------------------------------------------------- | +| **`pure_symbol_title_bar_separator`** | `-` | Separator in terminal's windows title. | +| **`pure_shorten_window_title_current_directory_length`** | `0` | Shorten every window title path component but the last to X characters (0 do not shorten) | + +### Current Working Directory + +| Option | Default | Description | +| :------------------------------------------------- | :------ | :---------------------------------------------------------------------------------- | +| **`pure_begin_prompt_with_current_directory`** | `true` | `true`: _`pwd` `git`, `SSH`, duration_.
`false`: _`SSH` `pwd` `git`, duration_. | +| **`pure_shorten_prompt_current_directory_length`** | `0` | Shorten every prompt path component but the last to X characters (0 do not shorten) | + +### Check For New Release + +| Option | Default | Description | +| :------------------------------- | :------ | :-------------------------------------------------------- | +| **`pure_check_for_new_release`** | `false` | `true`: check repo for new release (on every shell start) | + +### Single Line Prompt + +| Option | Default | Description | +| :----------------------------------- | :------ | :-------------------------------------- | +| **`pure_enable_single_line_prompt`** | `false` | `true`: Compact prompt as a single line | + +### Separate Error Symbol + +| Option | Default | Description | +| :---------------------------------- | :------ | :------------------------------------------------------------------ | +| **`pure_separate_prompt_on_error`** | `false` | Show last command [exit code as a second prompt symbol][exit-code]. | + +### Jobs + +| Option | Default | Description | +| :------------------- | :------ | :-------------------------- | +| **`pure_show_jobs`** | `false` | Show Number of running jobs | diff --git a/docs/components/features-overview.md b/docs/components/features-overview.md new file mode 100644 index 00000000..f50781ca --- /dev/null +++ b/docs/components/features-overview.md @@ -0,0 +1,30 @@ +### Overview + +Fully **customizable** (colors, symbols and features): + +* Excellent prompt character `❯` : + * Change `❯` to red when previous command has failed ; + * Start prompt with _current working directory_ 🏴 ; + * Compact-mode (single-line prompt) 🏴 ; +* Display _current folder_ tail ; +* check for new release on start 🏴 ; +* Display _username_ and _hostname_ when in an `SSH` session ; +* Display command _duration_ when longer than `5` seconds ; +* Display `Python` _virtualenv_ when activated 🏴 ; +* Display `VI` mode and custom symbol for non-insert mode 🏴 ; +* Display `kubernetes` context and namespace 🏴 ; +* Display container indicator (e.g. `docker`, `podman`, `LXC`/`LXD`) 🏴 +* Show system time 🏴 ; +* Show number of running jobs 🏴 ; +* Prefix when `root` 🏴 ; +* Display `git` branch name 🏴 ; + * Display `*` when `git` repository is _dirty_ ; + * Display `≡` when `git` repository is _stashed_ ; + * Display `⇡` when branch is _ahead_ (commits to push) ; + * Display `⇣` when branch is _behind_ (commits to pull) ; + * Async update when [configured with fish-async-prompt](https://github.com/pure-fish/pure/wiki/Async-git-Prompt) ; +* Update terminal title with _current folder_ and _command_ ; +* Detect when running in a container ; +* Shorten _current folder_ component 🏴; + +🏴: Enabled or disabled via a [feature flag](#-features-flags). diff --git a/docs/components/installation.md b/docs/components/installation.md new file mode 100644 index 00000000..591c0dd6 --- /dev/null +++ b/docs/components/installation.md @@ -0,0 +1,21 @@ +!!! success + + Pure requires Fish **`≥3.x`** + +=== "[Fisher](https://github.com/jorgebucaran/fisher)" + + ```shell + fisher install pure-fish/pure + ``` + +=== "Manually" + + 1. Download the installer to `/tmp` + ```shell + curl git.io/pure-fish --output /tmp/pure_installer.fish --location --silent + ``` + + 2. Source and trigger the installer + ``` + source /tmp/pure_installer.fish; and install_pure + ``` diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 00000000..9c0b4b2f --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,5 @@ +# Contribution Guide + +{% include '../CODE_OF_CONDUCT.md' %} +{% include '../CONTRIBUTING.md' %} +{% include './RELEASE.md' %} diff --git a/docs/index.md b/docs/index.md index 874e827e..fc3314ad 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,6 +2,7 @@
+ [![ci-status]][ci-link] ![fish-3] [![release-version]][release-link] [![sponsors]][sponsor-link] @@ -12,146 +13,22 @@ ## :rocket: Install -**:warning: requirements**: fish `≥3.x` - -### [Fisher](https://github.com/jorgebucaran/fisher) - -```shell -fisher install pure-fish/pure -``` - -### Manually - -Via [cURL](https://curl.haxx.se): - -```shell -# Download the installer to `/tmp` -curl git.io/pure-fish --output /tmp/pure_installer.fish --location --silent -# Source and trigger the installer -source /tmp/pure_installer.fish; and install_pure -``` - -## Features - -Fully **customizable** (colors, symbols and features): - -* Excellent prompt character `❯` : - * Change `❯` to red when previous command has failed ; - * Start prompt with _current working directory_ 🏴 ; - * Compact-mode (single-line prompt) 🏴 ; -* Display _current folder_ tail ; -* check for new release on start 🏴 ; -* Display _username_ and _hostname_ when in an `SSH` session ; -* Display command _duration_ when longer than `5` seconds ; -* Display `Python` _virtualenv_ when activated 🏴 ; -* Display `VI` mode and custom symbol for non-insert mode 🏴 ; -* Display `kubernetes` context and namespace -* Display container indicator (e.g. `docker`, `podman`, `LXC`/`LXD`) 🏴 -* Show system time 🏴 ; -* Show number of running jobs 🏴 ; -* Prefix when `root` 🏴 ; -* Display `git` branch name 🏴 ; - * Display `*` when `git` repository is _dirty_ ; - * Display `≡` when `git` repository is _stashed_ ; - * Display `⇡` when branch is _ahead_ (commits to push) ; - * Display `⇣` when branch is _behind_ (commits to pull) ; - * Async update when [configured with fish-async-prompt](https://github.com/pure-fish/pure/wiki/Async-git-Prompt) ; -* Update terminal title with _current folder_ and _command_ ; -* Detect when running in a container ; -* Shorten _current folder_ component 🏴; - -🏴: Enabled or disabled via a [feature flag](#-features-flags). +{% include 'components/installation.md' %} ## :paintbrush: Configuration -You can tweak `pure` behavior and color by changing [universal variables](https://fishshell.com/docs/current/tutorial.html#tut_universal) either directly in the terminal or in your `config.fish`, _e.g._: - -```shell -set --universal pure_show_system_time true -set --universal pure_color_system_time pure_color_mute -``` - -### Prompt Symbol - -| Option | Default | Description | -| :------------------------------------- | :------ | :--------------------------------------------------------------------------- | -| **`pure_symbol_container_prefix`** | | Prefix when being inside a container ([to customize][to-set]) | -| **`pure_symbol_git_dirty`** | `*` | Repository is Dirty (uncommitted/untracked changes). | -| **`pure_symbol_git_stash`** | `≡` | Repository git stash status. | -| **`pure_symbol_git_unpulled_commits`** | `⇣` | Branch is behind upstream (commits to pull). | -| **`pure_symbol_git_unpushed_commits`** | `⇡` | Branch is ahead upstream (commits to push). | -| **`pure_symbol_k8s_prefix`** | `☸` | Prefix when being connected to Kubernetes/K8s | -| **`pure_symbol_prefix_root_prompt`** | `#` | Prefix prompt when logged in as `root`. | -| **`pure_symbol_prompt`** | `❯` | Prompt symbol. | -| **`pure_symbol_reverse_prompt`** | `❮` | VI non-insert mode symbol. | -| **`pure_symbol_ssh_prefix`** | | Prefix when being connected to SSH session (default: [undefined][to-set]) | -| **`pure_symbol_title_bar_separator`** | `-` | Separator in terminal's windows title. | -| **`pure_symbol_virtualenv_prefix`** | | Prefix when a Python virtual env is activated (default: [undefined][to-set]) | - -> :information_source: Need [safer `git` symbols](https://github.com/sindresorhus/pure/wiki/Customizations,-hacks-and-tweaks#safer-symbols)? - -### 🔌 Features' Flags +{% include 'components/configuration.md' %} -| Option | Default | Description | -| :------------------------------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **`pure_begin_prompt_with_current_directory`** | `true` | `true`: _`pwd` `git`, `SSH`, duration_.
`false`: _`SSH` `pwd` `git`, duration_. | -| **`pure_check_for_new_release`** | `false` | `true`: check repo for new release (on every shell start) | -| **`pure_enable_container_detection`** | `true` | `false`: Do not check if run in container (e.g. `docker`, `podman`, `LXC`/`LXD`, etc.).
:warning: Detection is a bit [tricky across OSes][container-detection]. | -| **`pure_enable_git`** | `true` | Show info about Git repository. | -| **`pure_enable_k8s`** | `false` | `true`: shows `kubernetes` context and namespace. | -| **`pure_enable_single_line_prompt`** | `false` | `true`: Compact prompt as a single line | -| **`pure_enable_virtualenv`** | `true` | Show virtual env name (based on `VIRTUAL_ENV` or `CONDA_DEFAULT_ENV`). | -| **`pure_reverse_prompt_symbol_in_vimode`** | `true` | `true`: `❮` indicate a non-insert mode.
`false`: indicate vi mode with `[I]`, `[N]`, `[V]`. | -| **`pure_separate_prompt_on_error`** | `false` | Show last command [exit code as a separate character][exit-code]. | -| **`pure_shorten_prompt_current_directory_length`** | `0` | Shorten every prompt path component but the last to X characters (0 do not shorten) | -| **`pure_shorten_window_title_current_directory_length`** | `0` | Shorten every window title path component but the last to X characters (0 do not shorten) | -| **`pure_show_jobs`** | `false` | Show Number of running jobs | -| **`pure_show_prefix_root_prompt`** | `false` | `true`: shows prompt prefix when logged in as `root`. | -| **`pure_show_subsecond_command_duration`** | `false` | Show subsecond (ex. 1.5s) in command duration. | -| **`pure_show_system_time`** | `false` | `true`: shows system time before the prompt symbol (as `%H:%M:%S`). | -| **`pure_threshold_command_duration`** | `5` | Show command duration when above this value (seconds). | - -### 🎨 Colours - -> :information_source: See [`set_color`][fish-set-color] documentation for full possibilities. - -> :warning: The absence of `$` sign is expected in `pure_` named colours. - -| Base Color | Inherited by | Default | -| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------- | -| **`pure_color_danger`** | **`pure_color_prompt_on_error`** | `red` | -| **`pure_color_dark`** | | `black` | -| **`pure_color_info`** | **`pure_color_git_unpulled_commits`**
**`pure_color_git_unpushed_commits`** | `cyan` | -| **`pure_color_light`** | **`pure_color_username_root`** | `white` | -| **`pure_color_mute`** | **`pure_color_git_branch`**
**`pure_color_git_dirty`**
**`pure_color_git_stash`**
**`pure_color_hostname`**
**`pure_color_at_sign`**
**`pure_color_username_normal`**
**`pure_color_virtualenv`** | `brblack` | -| **`pure_color_normal`** | **`pure_color_jobs`** | `normal` | -| **`pure_color_primary`** | **`pure_color_current_directory`** | `blue` | -| **`pure_color_success`** | **`pure_color_prompt_on_success`** | `magenta` | -| **`pure_color_warning`** | **`pure_color_command_duration`** | `yellow` | - -## :+1: Contribute - -**requirements:** [`docker`](https://docs.docker.com/install/) (isolate from your environment), get familiar with [CONTRIBUTING.md][contributing] guidelines. - -Specify the [`FISH_VERSION`][fish-releases] you want, and the `CMD` executed by the container: - - make build-pure-on FISH_VERSION=3.3.1 - make dev-pure-on FISH_VERSION=3.3.1 CMD="fishtape tests/*.test.fish" - -## :man_technologist: Maintainer - -* [Édouard Lopez](https://github.com/edouard-lopez) - -## :clap: Thanks +## Features -* [@andreiborisov](https://github.com/andreiborisov) for the [docker images][docker-images] ; -* [@jorgebucaran](https://github.com/jorgebucaran/) for [fishtape](https://github.com/jorgebucaran/fishtape) ; -* [@rafaelrinaldi](https://github.com/pure-fish/pure) for starting the project ; +{% include 'components/features-overview.md' %} +{% include 'components/features-list.md' %} -## :classical_building: License +## 🎨 Colours -[MIT][MIT] +{% include 'components/colours.md' %} + [to-set]: #paintbrush-configuration [ci-link]: "Github CI" [ci-status]: https://img.shields.io/github/actions/workflow/status/pure-fish/pure/.github/workflows/ci.yml?style=flat-square @@ -159,9 +36,6 @@ Specify the [`FISH_VERSION`][fish-releases] you want, and the `CMD` executed by [fish-3]: "Support Fish 3" [exit-code]: "See pure-zsh wiki" [fish-releases]: https://github.com/fish-shell/fish-shell/releases -[docker-images]: https://github.com/andreiborisov/docker-fish/ -[MIT]: LICENSE.md -[fish-set-color]: https://fishshell.com/docs/current/cmds/set_color.html [container-detection]: https://stackoverflow.com/q/23513045/802365 [release-version]: https://img.shields.io/github/v/tag/pure-fish/pure?label=latest%20&style=flat-square @@ -170,3 +44,4 @@ Specify the [`FISH_VERSION`][fish-releases] you want, and the `CMD` executed by [sponsor-link]: https://github.com/sponsors/edouard-lopez/ "Become a sponsor" [contributing]: CONTRIBUTING.md + diff --git a/makefile b/makefile index 386232b5..33e3bf81 100644 --- a/makefile +++ b/makefile @@ -105,6 +105,6 @@ serve-pure-doc: --publish 8000:8000 \ --env "DEV_ADDR=0.0.0.0:8000" \ --env "LIVE_RELOAD_SUPPORT=true" \ - --env ADD_MODULES="mkdocs-material mkdocs-awesome-pages-plugin mkdocs-include-markdown-plugin" \ + --env ADD_MODULES="pymdown-extensions mkdocs-material mkdocs-awesome-pages-plugin mkdocs-include-markdown-plugin" \ --volume=$$(pwd):/mkdocs \ polinux/mkdocs diff --git a/mkdocs.yml b/mkdocs.yml index 52497b58..4263b6c5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -15,15 +15,15 @@ theme: - navigation.tracking - navigation.expand - navigation.indexes - logo: spinak_iac.png - favicon: spinak_iac.png + # logo: pure.png + # favicon: pure.png icon: repo: fontawesome/brands/gitlab admonition: note: octicons/tag-16 abstract: octicons/checklist-16 info: octicons/info-16 - tip: octicons/squirrel-16 + tip: octicons/light-bulb-16 success: octicons/check-16 question: octicons/question-16 warning: octicons/alert-16 @@ -51,15 +51,15 @@ theme: markdown_extensions: - admonition - # - attr_list - # - md_in_html - # - pymdownx.details - # - pymdownx.superfences - # - pymdownx.tabbed: - # alternate_style: true - # - pymdownx.highlight - # - pymdownx.inlinehilite - # - pymdownx.snippets + # - attr_list + # - md_in_html + - pymdownx.details + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - pymdownx.highlight + - pymdownx.inlinehilite + - pymdownx.snippets - pymdownx.emoji: emoji_index: !!python/name:materialx.emoji.twemoji emoji_generator: !!python/name:materialx.emoji.to_svg @@ -68,6 +68,6 @@ markdown_extensions: plugins: - # - search + - search - awesome-pages - include-markdown From eaeffcb8370158b745419cd4390debeaf3fbf255 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89douard=20Lopez?= Date: Fri, 19 Jan 2024 20:44:13 +0100 Subject: [PATCH 3/5] ci: publish documentation to gh-pages see https://pure-fish.github.io/pure/ --- .github/workflows/ci.yml | 4 ++++ .github/workflows/doc.yml | 31 +++++++++++++++++++++++++++++++ docker/doc.Dockerfile | 20 ++++++-------------- docs/requirements.txt | 4 ++++ makefile | 21 +++++++++------------ 5 files changed, 54 insertions(+), 26 deletions(-) create mode 100644 .github/workflows/doc.yml create mode 100644 docs/requirements.txt diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2dec2914..9479f199 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -75,3 +75,7 @@ jobs: if: contains(github.ref, 'master') uses: ./.github/workflows/bump-version.yml secrets: inherit + + publish-doc: + uses: ./.github/workflows/doc.yml + secrets: inherit diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml new file mode 100644 index 00000000..f49e64fb --- /dev/null +++ b/.github/workflows/doc.yml @@ -0,0 +1,31 @@ +name: Publish docs via GitHub Pages +on: + push: + branches: + - master + paths: + - docs/ + + pull_request: + # types: + # - opened + # - reopened + # - synchronize + # - ready_for_review + paths: + - docs/ + workflow_call: + +jobs: + build: + name: Deploy docs + runs-on: ubuntu-latest + steps: + - name: Checkout repo + uses: actions/checkout@v4 + + - name: Deploy docs + uses: mhausenblas/mkdocs-deploy-gh-pages@master + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + REQUIREMENTS: docs/requirements.txt diff --git a/docker/doc.Dockerfile b/docker/doc.Dockerfile index df9b50e3..16b03b79 100644 --- a/docker/doc.Dockerfile +++ b/docker/doc.Dockerfile @@ -1,17 +1,9 @@ -FROM python:3 - -# Create app directory -WORKDIR /usr/src/app +FROM squidfunk/mkdocs-material:9 +COPY ./docs/requirements.txt /docs/ RUN pip install \ - mkdocs \ - mkdocs-pdf-export-plugin \ - mkdocs-material - -COPY . . - -# RUN mkdocs build + --no-cache-dir \ + --requirement ./requirements.txt -EXPOSE 8000 -# CMD ["python", "-m", "http.server", "8000", "-d", "./site"] -CMD ["mkdocs" "serve" "--clean"] +ENTRYPOINT ["mkdocs"] +CMD ["serve", "--dev-addr=0.0.0.0:8000"] diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..354c7c38 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +pymdown-extensions +mkdocs-material +mkdocs-awesome-pages-plugin +mkdocs-include-markdown-plugin diff --git a/makefile b/makefile index 33e3bf81..dbd209ae 100644 --- a/makefile +++ b/makefile @@ -89,13 +89,6 @@ test-pure-on-nix: $(MAKE) dev-pure-on-nix CMD="${CMD}" TTY= -build-pure-doc: - docker build \ - --file ./docker/doc.Dockerfile \ - --tag=pure-doc \ - --load \ - ./ - serve-pure-doc: docker run \ --name mkdocs \ @@ -103,8 +96,12 @@ serve-pure-doc: --interactive \ --rm \ --publish 8000:8000 \ - --env "DEV_ADDR=0.0.0.0:8000" \ - --env "LIVE_RELOAD_SUPPORT=true" \ - --env ADD_MODULES="pymdown-extensions mkdocs-material mkdocs-awesome-pages-plugin mkdocs-include-markdown-plugin" \ - --volume=$$(pwd):/mkdocs \ - polinux/mkdocs + --volume=$$(pwd):/docs \ + pure-doc + +build-pure-doc: + docker build \ + --file ./docker/doc.Dockerfile \ + --tag=pure-doc \ + --load \ + ./ From 0d54a207114860449b4a8532826bf3362773370c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89douard=20Lopez?= Date: Fri, 19 Jan 2024 23:36:48 +0100 Subject: [PATCH 4/5] docs: improve ux --- CONTRIBUTING.md | 2 +- docs/assets/favicon.png | Bin 0 -> 5921 bytes docs/index.md | 3 -- docs/requirements.txt | 3 ++ mkdocs.yml | 68 +++++++++++++++++++++++++++++----------- 5 files changed, 53 insertions(+), 23 deletions(-) create mode 100644 docs/assets/favicon.png diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 47046f8a..05ea0a6e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -## :+1: Contribute +## :+1: Work inside a Docker !!! info diff --git a/docs/assets/favicon.png b/docs/assets/favicon.png new file mode 100644 index 0000000000000000000000000000000000000000..b9435fdeabc34afc6eb101e513e8e4be92b38847 GIT binary patch literal 5921 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 z
- -[![ci-status]][ci-link] ![fish-3] [![release-version]][release-link] [![sponsors]][sponsor-link] - # pure diff --git a/docs/requirements.txt b/docs/requirements.txt index 354c7c38..f3df00c9 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -2,3 +2,6 @@ pymdown-extensions mkdocs-material mkdocs-awesome-pages-plugin mkdocs-include-markdown-plugin +mkdocs-git-committers-plugin-2 +mkdocs-git-authors-plugin + diff --git a/mkdocs.yml b/mkdocs.yml index 4263b6c5..f865101b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,21 +4,34 @@ site_author: "Édouard Lopez" docs_dir: docs/ repo_name: "pure-fish/pure" repo_url: "https://github.com/pure-fish/pure" + nav: - Home: index.md theme: - # name: "material" name: "material" include_sidebar: true features: - - navigation.tabs - - navigation.tracking + - content.action.edit + - content.code.copy - navigation.expand + - navigation.footer - navigation.indexes - # logo: pure.png - # favicon: pure.png + - navigation.instant + - navigation.instant + - navigation.instant.progress + - navigation.path + - navigation.sections + - navigation.tabs + - navigation.top + - navigation.tracking + - search.suggest + - search.highlight + + logo: ./assets/favicon.png + favicon: ./assets/favicon.png + icon: - repo: fontawesome/brands/gitlab + repo: fontawesome/brands/github admonition: note: octicons/tag-16 abstract: octicons/checklist-16 @@ -32,27 +45,30 @@ theme: bug: octicons/bug-16 example: octicons/beaker-16 quote: octicons/quote-16 + palette: - - scheme: default - primary: teal - accent: teal + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: deep purple toggle: - icon: material/toggle-switch-off-outline + icon: material/brightness-7 name: Switch to dark mode - - scheme: slate - primary: teal - accent: teal + + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: purple toggle: - icon: material/toggle-switch + icon: material/brightness-2 name: Switch to light mode + font: - text: Open Sans + text: Roboto code: Roboto Mono markdown_extensions: - admonition - # - attr_list - # - md_in_html - pymdownx.details - pymdownx.superfences - pymdownx.tabbed: @@ -63,11 +79,25 @@ markdown_extensions: - pymdownx.emoji: emoji_index: !!python/name:materialx.emoji.twemoji emoji_generator: !!python/name:materialx.emoji.to_svg - # - toc: - # permalink: true + - toc: + permalink: true + toc_depth: 3 +extra: + social: + - icon: fontawesome/brands/mastodon + link: https://piaille.fr/@edouard_lopez + - icon: fontawesome/brands/twitter + link: https://twitter.com/edouard_lopez + - icon: fontawesome/brands/github + link: https://github.com/pure-fish/pure/ plugins: - search - awesome-pages - include-markdown + - git-committers: + repository: pure-fish/pure + branch: master + # enabled: !ENV [CI, false] + - git-authors From 9cea5455fcdea18499a4f38e48e1108fa493cb0a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89douard=20Lopez?= Date: Fri, 19 Jan 2024 23:37:09 +0100 Subject: [PATCH 5/5] docs: revamp README to redirect towards mkdocs --- README.md | 136 +++++++++++------------------------------------------- 1 file changed, 28 insertions(+), 108 deletions(-) diff --git a/README.md b/README.md index 93ba0275..188a8233 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,7 @@ -> ##### :arrow_up: Hey! Want to migrate from v3.x to v4.x? Check our [**migration guide**](https://github.com/pure-fish/pure/releases/tag/v4.0.0), done with ❤️ - -# pure +# pure `❯❮❯` > Pretty, minimal and fast Fish 🐟 prompt, ported from [`zsh`](https://github.com/sindresorhus/pure). @@ -17,25 +15,16 @@ Pure with light colorscheme -## :rocket: Install - -**:warning: requirements**: fish `≥3.x` +## Documentation -### [Fisher](https://github.com/jorgebucaran/fisher) +:sparkles: Check-out our [brand-new documentation][doc] for configurations, features and colours as well as contributing guide. -```shell -fisher install pure-fish/pure -``` - -### Manually +## :rocket: Install -Via [cURL](https://curl.haxx.se): +**:warning: requirements**: fish `≥3.x`, [fisher](https://github.com/jorgebucaran/fisher): ```shell -# Download the installer to `/tmp` -curl git.io/pure-fish --output /tmp/pure_installer.fish --location --silent -# Source and trigger the installer -source /tmp/pure_installer.fish; and install_pure +fisher install pure-fish/pure ``` ## Features @@ -67,113 +56,44 @@ Fully **customizable** (colors, symbols and features): - Detect when running in a container ; - Shorten _current folder_ component 🏴; -🏴: Enabled or disabled via a [feature flag](#-features-flags). +🏴: Enabled or disabled via a [feature flag][features]. -## :paintbrush: Configuration +## Configuration -You can tweak `pure` behavior and color by changing [universal variables](https://fishshell.com/docs/current/tutorial.html#tut_universal) either directly in the terminal or in your `config.fish`, _e.g._: +See [How to configure pure prompt?][configure] -```shell -set --universal pure_show_system_time true -set --universal pure_color_system_time pure_color_mute -``` +## Features' Flags + +See [Features and their respective options][features]. + +## :heart: Contribute -### Prompt Symbol - -| Option | Default | Description | -| :------------------------------------- | :------ | :--------------------------------------------------------------------------- | -| **`pure_symbol_container_prefix`** | | Prefix when being inside a container ([to customize][to-set]) | -| **`pure_symbol_git_dirty`** | `*` | Repository is Dirty (uncommitted/untracked changes). | -| **`pure_symbol_git_stash`** | `≡` | Repository git stash status. | -| **`pure_symbol_git_unpulled_commits`** | `⇣` | Branch is behind upstream (commits to pull). | -| **`pure_symbol_git_unpushed_commits`** | `⇡` | Branch is ahead upstream (commits to push). | -| **`pure_symbol_k8s_prefix`** | `☸` | Prefix when being connected to Kubernetes/K8s | -| **`pure_symbol_prefix_root_prompt`** | `#` | Prefix prompt when logged in as `root`. | -| **`pure_symbol_prompt`** | `❯` | Prompt symbol. | -| **`pure_symbol_reverse_prompt`** | `❮` | VI non-insert mode symbol. | -| **`pure_symbol_ssh_prefix`** | | Prefix when being connected to SSH session (default: [undefined][to-set]) | -| **`pure_symbol_title_bar_separator`** | `-` | Separator in terminal's windows title. | -| **`pure_symbol_virtualenv_prefix`** | | Prefix when a Python virtual env is activated (default: [undefined][to-set]) | - -> :information_source: Need [safer `git` symbols](https://github.com/sindresorhus/pure/wiki/Customizations,-hacks-and-tweaks#safer-symbols)? - -### 🔌 Features' Flags - -| Option | Default | Description | -| :------------------------------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **`pure_begin_prompt_with_current_directory`** | `true` | `true`: _`pwd` `git`, `SSH`, duration_.
`false`: _`SSH` `pwd` `git`, duration_. | -| **`pure_check_for_new_release`** | `false` | `true`: check repo for new release (on every shell start) | -| **`pure_enable_container_detection`** | `true` | `false`: Do not check if run in container (e.g. `docker`, `podman`, `LXC`/`LXD`, etc.).
:warning: Detection is a bit [tricky across OSes][container-detection]. | -| **`pure_enable_git`** | `true` | Show info about Git repository. | -| **`pure_enable_k8s`** | `false` | `true`: shows `kubernetes` context and namespace. | -| **`pure_enable_single_line_prompt`** | `false` | `true`: Compact prompt as a single line | -| **`pure_enable_virtualenv`** | `true` | Show virtual env name (based on `VIRTUAL_ENV` or `CONDA_DEFAULT_ENV`). | -| **`pure_reverse_prompt_symbol_in_vimode`** | `true` | `true`: `❮` indicate a non-insert mode.
`false`: indicate vi mode with `[I]`, `[N]`, `[V]`. | -| **`pure_separate_prompt_on_error`** | `false` | Show last command [exit code as a separate character][exit-code]. | -| **`pure_shorten_prompt_current_directory_length`** | `0` | Shorten every prompt path component but the last to X characters (0 do not shorten) | -| **`pure_shorten_window_title_current_directory_length`** | `0` | Shorten every window title path component but the last to X characters (0 do not shorten) | -| **`pure_show_jobs`** | `false` | Show Number of running jobs | -| **`pure_show_prefix_root_prompt`** | `false` | `true`: shows prompt prefix when logged in as `root`. | -| **`pure_show_subsecond_command_duration`** | `false` | Show subsecond (ex. 1.5s) in command duration. | -| **`pure_show_system_time`** | `false` | `true`: shows system time before the prompt symbol (as `%H:%M:%S`). | -| **`pure_threshold_command_duration`** | `5` | Show command duration when above this value (seconds). | - -### 🎨 Colours - -> :information_source: See [`set_color`][fish-set-color] documentation for full possibilities. - -> :warning: The absence of `$` sign is expected in `pure_` named colours. - -| Base Color | Inherited by | Default | -| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------- | -| **`pure_color_danger`** | **`pure_color_prompt_on_error`** | `red` | -| **`pure_color_dark`** | | `black` | -| **`pure_color_info`** | **`pure_color_git_unpulled_commits`**
**`pure_color_git_unpushed_commits`** | `cyan` | -| **`pure_color_light`** | **`pure_color_username_root`** | `white` | -| **`pure_color_mute`** | **`pure_color_git_branch`**
**`pure_color_git_dirty`**
**`pure_color_git_stash`**
**`pure_color_hostname`**
**`pure_color_at_sign`**
**`pure_color_username_normal`**
**`pure_color_virtualenv`** | `brblack` | -| **`pure_color_normal`** | **`pure_color_jobs`** | `normal` | -| **`pure_color_primary`** | **`pure_color_current_directory`** | `blue` | -| **`pure_color_success`** | **`pure_color_prompt_on_success`** | `magenta` | -| **`pure_color_warning`** | **`pure_color_command_duration`** | `yellow` | - -## :+1: Contribute - -**requirements:** [`docker`](https://docs.docker.com/install/) (isolate from your environment), get familiar with [CONTRIBUTING.md][contributing] guidelines. - -Specify the [`FISH_VERSION`][fish-releases] you want, and the `CMD` executed by the container: - - make build-pure-on FISH_VERSION=3.3.1 - make dev-pure-on FISH_VERSION=3.3.1 CMD="fishtape tests/*.test.fish" - -## :man_technologist: Maintainer - -- [Édouard Lopez](https://github.com/edouard-lopez) - -## :clap: Thanks - -- [@andreiborisov](https://github.com/andreiborisov) for the [docker images][docker-images] -- [@jorgebucaran](https://github.com/jorgebucaran/) for [fishtape](https://github.com/jorgebucaran/fishtape) +If you have any ideas or suggestions, we encourage you to submit a pull request. Our team will review and discuss your contribution. + +Checkout our [Contribution Guide][contribution] to get familiar with our conventions and requirements. + +## :man_technologist: People + +- [Édouard Lopez](https://github.com/edouard-lopez) product lead ; +- [@andreiborisov](https://github.com/andreiborisov) for the [docker images][docker-images] ; +- [@jorgebucaran](https://github.com/jorgebucaran/) for [fishtape](https://github.com/jorgebucaran/fishtape) ; - [@rafaelrinaldi](https://github.com/rafaelrinaldi) for starting the project and publishing the initial releases -## :classical_building: License +## [MIT][MIT] License -[MIT][MIT] +[doc]: https://pure-fish.github.io/pure/ +[configure]: https://pure-fish.github.io/pure/#configuration +[features]: https://pure-fish.github.io/pure/#overview +[contribution]:https://pure-fish.github.io/pure/contributing/ -[to-set]: #paintbrush-configuration [ci-link]: "Github CI" [ci-status]: https://img.shields.io/github/actions/workflow/status/pure-fish/pure/.github/workflows/ci.yml?style=flat-square [fish-3]: "Support Fish 3" -[exit-code]: "See pure-zsh wiki" -[fish-releases]: https://github.com/fish-shell/fish-shell/releases [docker-images]: https://github.com/andreiborisov/docker-fish/ [MIT]: LICENSE.md -[fish-set-color]: https://fishshell.com/docs/current/cmds/set_color.html -[container-detection]: https://stackoverflow.com/q/23513045/802365 [release-version]: https://img.shields.io/github/v/tag/pure-fish/pure?label=latest%20&style=flat-square [release-link]: https://github.com/pure-fish/pure/releases "GitHub tag (latest SemVer)" [sponsors]: https://img.shields.io/github/sponsors/edouard-lopez?label=💰&style=flat-square "GitHub Sponsors" [sponsor-link]: https://github.com/sponsors/edouard-lopez/ "Become a sponsor" - -[contributing]: CONTRIBUTING.md