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/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..05ea0a6e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,18 +1,23 @@ -# Contribution Guide +## :+1: Work inside a Docker -## 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/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 diff --git a/docker/doc.Dockerfile b/docker/doc.Dockerfile new file mode 100644 index 00000000..16b03b79 --- /dev/null +++ b/docker/doc.Dockerfile @@ -0,0 +1,9 @@ +FROM squidfunk/mkdocs-material:9 + +COPY ./docs/requirements.txt /docs/ +RUN pip install \ + --no-cache-dir \ + --requirement ./requirements.txt + +ENTRYPOINT ["mkdocs"] +CMD ["serve", "--dev-addr=0.0.0.0:8000"] 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/assets/favicon.png b/docs/assets/favicon.png new file mode 100644 index 00000000..b9435fde Binary files /dev/null and b/docs/assets/favicon.png differ 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/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/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 new file mode 100644 index 00000000..3fb1c22c --- /dev/null +++ b/docs/index.md @@ -0,0 +1,44 @@ +
+ +
+ +
+ +# pure + +{% include 'components/hero-banner.md' %} + +## :rocket: Install + +{% include 'components/installation.md' %} + +## :paintbrush: Configuration + +{% include 'components/configuration.md' %} + +## Features + +{% include 'components/features-overview.md' %} +{% include 'components/features-list.md' %} + +## 🎨 Colours + +{% 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 + +[fish-3]: "Support Fish 3" +[exit-code]: "See pure-zsh wiki" +[fish-releases]: https://github.com/fish-shell/fish-shell/releases +[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/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..f3df00c9 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,7 @@ +pymdown-extensions +mkdocs-material +mkdocs-awesome-pages-plugin +mkdocs-include-markdown-plugin +mkdocs-git-committers-plugin-2 +mkdocs-git-authors-plugin + diff --git a/makefile b/makefile index a4368e57..dbd209ae 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,21 @@ 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= + + +serve-pure-doc: + docker run \ + --name mkdocs \ + --tty \ + --interactive \ + --rm \ + --publish 8000:8000 \ + --volume=$$(pwd):/docs \ + pure-doc + +build-pure-doc: + docker build \ + --file ./docker/doc.Dockerfile \ + --tag=pure-doc \ + --load \ + ./ diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..f865101b --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,103 @@ +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" + include_sidebar: true + features: + - content.action.edit + - content.code.copy + - navigation.expand + - navigation.footer + - navigation.indexes + - 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/github + admonition: + note: octicons/tag-16 + abstract: octicons/checklist-16 + info: octicons/info-16 + tip: octicons/light-bulb-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: + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: deep purple + toggle: + icon: material/brightness-7 + name: Switch to dark mode + + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: purple + toggle: + icon: material/brightness-2 + name: Switch to light mode + + font: + text: Roboto + code: Roboto Mono + +markdown_extensions: + - admonition + - 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 + 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