Docs for 3.0 (#148) #313

denysdovhan · 2018-01-15T00:05:08Z

We accomplished all the work related to code in #148. Now it's time to update docs.

Simplify large README.md file. Use docs folder.
Update docs related to options. Remove old, add new. ( Update options documentation for 3.0 #294)
Describe internal API for section creators.
Provide an example of a good typical section for new contributors.
Add troubleshooting page with typical issues
- "I don't see icons in prompt?" (Can not show icons normally #106, Not all icons are displayed in terminal correctly #202, SPACESHIP_GIT_SYMBOL gives a " " 🤷🏽‍♂️ #179,  how to display it #151, Arrow icons are blank squares (Hyper on Windows with Bash) #220, font #258, Glyphs dont work in gnome terminal #279 and so on)
- Suggestions?…
Add note about Unicode Version 9 Width
Idea: Generate GitBook from docs on gh-pages and use it as a website.
Suggestions?…

denysdovhan · 2018-01-15T00:06:21Z

@salmanulfarzy @maximbaz @nfischer any suggestions or just thoughts?

Add Troubleshooting to docs

maximbaz

Already looking good, my questions/suggestions below.

maximbaz · 2018-01-15T11:06:05Z

README.md

  * `?` — untracked changes;
  * `+` — uncommitted changes in the index;
  * `!` — unstaged changes;
  * `✘` — deleted files;
-* Prompt character turns red if the last command exits with non-zero code.


This is still true, keep it maybe?

It's now the second item of the list. Look up ☝️

@maximbaz please, click Resolve button to hide this thread.

I don't have it...?

maximbaz · 2018-01-15T11:06:57Z

README.md

 * Current Python pyenv (`🐍`).
 * Current .NET SDK version, through dotnet-cli (`.NET`).
 * Current Ember.js version, through ember-cli (`🐹`).
 * Current Kubectl context (`☸️`).
+* Package version, if there's is a package in current directory (`📦`).


"package" is too ambiguous, npm package?

This section is aimed to work not only with npm-packages.

maximbaz · 2018-01-15T11:21:16Z

docs/Options.md

+
+### Time (`time`)
+
+Disabled as default. Set `SPACESHIP_TIME_SHOW` to `true` in your `.zshrc`, if you need to show time stamps.


"by default" sounds a bit better imho, same for "exit code" section below

maximbaz · 2018-01-15T11:25:12Z

docs/Options.md

+
+| Variable | Default | Meaning |
+| :------- | :-----: | ------- |
+| `SPACESHIP_USER_SHOW` | `true` | Show user section |


Are you planning to add details that there are 4 allowed values for this variable and describe their meaning, and if so, where? Currently I see true, I would guess that the value could also be false, but I wouldn't know about the existence of always or needed.

Hm I didn't ask correctly, I was meaning to ask this: where are you planning to document all available options? Directly here, or somewhere in a different section of the documentation? A nested table of some kind?

I think directly here. I'll figure out something.

maximbaz · 2018-01-15T11:27:59Z

docs/Options.md

+
+### Battery (`battery`)
+
+By default, Battery section is shown only if battery level is below `SPACESHIP_BATTERY_THRESHOLD` (default: 10%) or it's fully charged.  It can be made always visible by setting `SPACESHIP_BATTERY_ALWAYS_SHOW=true`.


There is no SPACESHIP_BATTERY_ALWAYS_SHOW anymore

salmanulfarzy · 2018-01-15T16:48:23Z

Presets wiki already show configurations, Where do you want example configuration ?

If you meant example for developing new sections, I think it would better fit in CONTRIBUTING.md. What do you think ?

denysdovhan · 2018-01-15T19:11:47Z

@salmanulfarzy can you check API docs. Any suggestions?

Where do you want example configuration?

Either on API page or CONTRIBUTING.md. Where's the best place for it?

maximbaz

Looking good - maybe "Approve" resolves comments? 🙂

salmanulfarzy

Changes in mercurial API and some suggestions

salmanulfarzy · 2018-01-16T02:22:43Z

README.md

@@ -82,7 +79,7 @@ You can find more examples with different color schemes in [Screenshots](https:/

 For correct work you will first need:

-* A [`zsh`](http://www.zsh.org/) (v5.0.5 or recent) must be installed
+* A [`zsh`](http://www.zsh.org/) (v5.0.6 or recent) must be installed


Even though 5.0.6 is known to work, I think it would be preferable to require latest version like 5.2.

Ubuntu 16.10 and above ships with 5.2

Ubuntu 16.04 LTS ships with 5.1.1

macOS 10.12 ships with 5.2

macOS 10.11 ships with 5.0.8

Why? If it works on lower versions, why wouldn't we keep them as required?

salmanulfarzy · 2018-01-16T02:36:41Z

docs/API.md

+
+## `spaceship::is_hg`
+
+The same as [`spaceship::is_git`](#spaceshipisgit), but for functions. This utility returns zero exit code if a current working directory is a Git repository and non-zero if it's not.


but for mercurial repositories.

working directory is a Mercurial repository and non-zero

salmanulfarzy · 2018-01-16T02:37:22Z

docs/API.md

+
+### Arguments
+
+1. `deprecated` _Required_ — the name of a deprecated variable. If this variable is set (contains any value), then `"%B$deprecated%b is deprecated.` will be printed.


Can we add a note about %B...%b, So users would know what it is ?

nfischer · 2018-01-16T07:53:22Z

docs/API.md

+
+This command validates that given program is available for execution. It returns zero exit code if a `command` exists and non-zero if `command` doesn't.
+
+You can use this utility to check if some program is installed and perform actions conditionally. For example, you can either return an error and exit or continue script's execution.


Why do we need this instead of which? Does spaceship::exists foo succeed or fail if foo is a function?

Check if a program exists from a Bash script
— here's quite comprehensive explanation why we should not rely on which.

That is all true for bash, but not for zsh. In zsh:

% which which which: shell built-in command

I see your implementation is built on top of command -v, which I believe will have the same basic behavior as which in zsh. I think the current implementation is fine, but it would be nice to document that spaceship::exists checks for PATH binaries, functions, and builtins.

denysdovhan · 2018-01-16T23:57:58Z

Just finished with docs. I think it's ready to merge.

@salmanulfarzy @maximbaz and @nfischer, please, reread docs carefully to make sure we didn't miss anything important 🙏

After merging this PR, #148 is ready to release. 🎉 🎉 🎉

maximbaz

Nice job, awesome to see 3.0 released 👏

maximbaz · 2018-01-17T00:07:45Z

docs/API.md

+
+## `SPACESHIP_ROOT`
+
+> **Attention!** Do not modify the value of this variable! Changing the value may cause the damage of Spaceship installation!


"damage to" may sound better

maximbaz · 2018-01-17T00:14:52Z

docs/Options.md

+
+> Works only for npm at the moment. Please, help us improve this section!
+
+Package version is shown when repository is a package (contains a `package.json` file). This is the version of the package you are working on, not the version of package manager itself.


Since it will support not only npm packages, I'd spell it like this:

... (e.g. contains a `package.json file). Note: this is the version...

maximbaz · 2018-01-17T00:23:52Z

docs/Options.md

+| `false`                  | Hidden          | Hidden          | Hidden        |
+| `always`                 | Shown           | Shown           | Shown         |
+| `true`                   | Shown           | Hidden          | Shown         |
+| `low`                    | Shown           | Hidden          | Hidden        |


This is definitely optional, but I must say, I wish all of the tables were formatted like this one, it's so much nicer to look at properly formatted tables like this one comparing to the tables like the one above. Even thought they are both rendered identically, I'm usually reviewing a non-rendered version, just because it's easier to immediately leave comments.

Many editors have some kind of "table formatter" extensions to do this automatically.

I was just thinking about this and https://github.com/prettier/prettier does an awesome job formatting markdown documents. Have a look at salmanulfarzy@57fa72f and raw file here

Thank you for this tip, definitely going to use it myself!

Just a note, prettier renders columns containing `` incorrectly (see for example Options.md:464), but I already reported this prettier/prettier#3753

UPDATE: also this: prettier/prettier#3754.

I agree, but it's hard to maintain proper formatting for tables in long terms. Constant reformating to keep the same width for each row would kill git history related to these rows.

When I initially released Spaceship, I tried to maintain table formatting, but soon I realized that this doesn't play well for me.

Tools like Prettier would help much with maintaining formatting, but for now, it doesn't support shell scripts. I'd prefer to postpone adding Prettier right now.

maximbaz · 2018-01-17T00:27:04Z

docs/Troubleshooting.md

+* Install any powerline compatible font like [Fira Code](https://github.com/tonsky/FiraCode) or [others](https://github.com/powerline/fonts).
+* Configure your terminal emulator to [use that font](https://powerline.readthedocs.io/en/master/troubleshooting/osx.html).
+
+## What's the weird characters infront of sections?


"character in front of a section" sounds better

maximbaz · 2018-01-17T00:29:01Z

docs/Troubleshooting.md

+  ```
+* Configure your terminal emulator to use UTF-8 as character encoding.
+
+## Some of sections icons put on one another?


Some section icons overlap each other?

Fixed. Perks of being a non-native speaker 😁

maximbaz · 2018-01-17T00:31:15Z

docs/Troubleshooting.md

+* Check _Threat ambiguous-width characters as double-width_.
+* Reload terminal's tab.
+
+## Why my prompt doesn't work like on preview?


Why doesn't my prompt look like the preview?

salmanulfarzy

Great job @denysdovhan, Some minor suggestions.

salmanulfarzy · 2018-01-17T00:40:42Z

docs/API.md

+
+  # Show foobar section only when there are foobar-specific files
+  # in current working direcotory
+  [[ -f foobar.conf || -n *.foo(#qN^/) || -n *.bar(#qN^/) ]] || return


Can we have a short note or link about glob qualifiers ?

Maybe we could make a spaceship API to perform -n *.<some extension>(#qN^/). This reduces lots of repetition.

Adding API is an interesting idea, but let's postpone it. For now, I've added a link to docs about glob qualifiers.

salmanulfarzy · 2018-01-17T00:53:44Z

README.md

+* Symlink `spaceship.zsh` to somewhere in [`$fpath`](http://www.refining-linux.org/archives/46/ZSH-Gem-12-Autoloading-functions/) as `prompt_spaceship_setup`.
+* Initialize prompt system and choose `spaceship`.
+
+#### Example


Not mentioning prezto might confuse users about installation method.

Do you mean adding a section on how to install it with prezto? But the theme is not even added yet in prezto-contrib, sorin-ionescu/prezto#1504

Most Zsh frameworks and Zsh plugin managers except prezto are specified in installation methods. spaceship wasn't compatible with prezto till 3.0, So users might assume the same.

It would be great if we at least specify how to install spaceship on prezto.

I don't use prezto. Can you add a section about installing for its users?

prezto follows vanilla Zsh prompt setup, Manual installation methods will get the job done. But we just haven't specified it anywhere.

salmanulfarzy · 2018-01-17T01:03:37Z

docs/README.md

+# Summary
+
+* [Home](README.md)
+* [Options](./docs/Options.md)


Wouldn't this nest docs folder twice ? Like, https://github.com/denysdovhan/spaceship-zsh-theme/blob/3.0-docs/docs/docs/Options.md#time-time

Nope. ./SUMMARY.md is link to ./docs/README.md. GitBook uses SUMMARY.md as an entry point. Everything works well here.

Everything works well here.

Then great

maximbaz · 2018-01-17T10:51:51Z

docs/Options.md

+| Variable | Default | Meaning |
+| :------- | :-----: | ------- |
+| `SPACESHIP_GIT_SHOW` | `true` | Show Git section |
+| `SPACESHIP_GIT_PREFIX` | `on ` | Prefix before Git section |


Markdown will strip the leading and trailing whitespaces in inline code blocks, so rendered documentation will be incorrect!

See this for context: #313 (comment) and prettier/prettier#3754

UPDATE: We can use (U+00A0 NO-BREAK SPACE) to overcome this issue.

Using NO-BREAK SPACES don't help with GitBook. It still strips trailing space.

@maximbaz can you help with that?

sure, but what's the plan then? Convert to no-break space and ignore that GitBook would still be incorrect?

@maximbaz let's fix this at least for GitHub. Please, keep spaces in code as is, replace only those in docs.

all right, I'll do it in an hour, need to shortly leave now.

no problem 👌
waiting for you PR

salmanulfarzy

Looks good 👍

denysdovhan · 2018-01-17T11:56:59Z

@salmanulfarzy @maximbaz please, review and make final approvement if everything is OK.

maximbaz · 2018-01-17T11:58:11Z

See the comment about whitespaces being stripped, that's the only one I have

Use no-break whitespace in markdown docs

denysdovhan · 2018-01-17T22:43:57Z

Merging this since changes were previously approved.

.npmignore -> package.json#files

c4ae456

denysdovhan added the help-wanted We need help to resolve this issue or PR. label Jan 15, 2018

denysdovhan added this to the v3.0 milestone Jan 15, 2018

denysdovhan assigned denysdovhan and salmanulfarzy Jan 15, 2018

Split README.md into docs/

b7a908c

denysdovhan mentioned this pull request Jan 15, 2018

3.0: Roadmap #200

Closed

25 tasks

salmanulfarzy and others added 2 commits January 15, 2018 12:56

Add Troubleshooting to docs

666117f

Merge pull request #314 from salmanulfarzy/add-troubleshooting

f266465

Add Troubleshooting to docs

denysdovhan added the docs Issue or PR is related to documentation. label Jan 15, 2018

maximbaz suggested changes Jan 15, 2018

View reviewed changes

denysdovhan added 4 commits January 15, 2018 14:34

Generate GitBook

4ac3970

Require zsh>=5.0.6

9162a84

Review fixes for @maximbaz

ce77fac

Update Troubleshooting.md

5bb13c0

Describe API methods

d3ec13f

maximbaz approved these changes Jan 15, 2018

View reviewed changes

salmanulfarzy requested changes Jan 16, 2018

View reviewed changes

salmanulfarzy mentioned this pull request Jan 16, 2018

Update options documentation for 3.0 #294

Merged

nfischer reviewed Jan 16, 2018

View reviewed changes

denysdovhan added 7 commits January 16, 2018 21:02

Fix problems in API.md

2269661

Add and example of typical section

7f518e7

Some fixes in API.md

f30efbe

Update Options.md

0847914

Fix missing SPACESHIP_CHAR_COLOR_SECONDARY

5d5bd36

More tweaks, add note about spaceship_ prefix

76518ee

Add TOC for docs

dc3f8c8

denysdovhan changed the title ~~WIP: Docs for 3.0 (#148)~~ Docs for 3.0 (#148) Jan 17, 2018

maximbaz approved these changes Jan 17, 2018

View reviewed changes

salmanulfarzy reviewed Jan 17, 2018

View reviewed changes

maximbaz reviewed Jan 17, 2018

View reviewed changes

Add review fixes

a00709a

salmanulfarzy approved these changes Jan 17, 2018

View reviewed changes

denysdovhan and others added 3 commits January 17, 2018 13:54

Add prezto installing method

e12fe2b

Capitalize Zsh. ZSH,zsh -> Zsh

cb9369c

Merge branch '3.0' into 3.0-docs

e8890ce

Use no-break whitespace in markdown docs

db08de3

maximbaz mentioned this pull request Jan 17, 2018

Use no-break whitespace in markdown docs #317

Merged

maximbaz added 9 commits January 17, 2018 14:35

Add space to to make sure empty is rendered correctly too

9fd3939

Mention markdown rendering pitfalls in CONTRIBUTING.md

07729b8

Run prettier, use fancy arrows

60674f0

Update hint for empty inline code block

9c907cd

Use middot to represent a space char

55d7a47

Update trailing whitespace example

abc2750

Mention the use of middot symbol in CONTRIBUTING.md

02acd55

Update missing icons

3a60a19

Try fewer backticks

2350610

nfischer approved these changes Jan 17, 2018

View reviewed changes

maximbaz and others added 2 commits January 17, 2018 23:04

Fix node symbol

60fd5d9

Merge pull request #317 from maximbaz/3.0-docs-whitespaces

f41c99e

Use no-break whitespace in markdown docs

denysdovhan merged commit 5dcd00e into 3.0 Jan 17, 2018

denysdovhan deleted the 3.0-docs branch January 17, 2018 22:44

salmanulfarzy mentioned this pull request Jan 19, 2018

Upgrade Zsh requirement to 5.1 #332

Closed


		### Time (`time`)

		Disabled as default. Set `SPACESHIP_TIME_SHOW` to `true` in your `.zshrc`, if you need to show time stamps.


		### Battery (`battery`)

		By default, Battery section is shown only if battery level is below `SPACESHIP_BATTERY_THRESHOLD` (default: 10%) or it's fully charged. It can be made always visible by setting `SPACESHIP_BATTERY_ALWAYS_SHOW=true`.


		## `spaceship::is_hg`

		The same as [`spaceship::is_git`](#spaceshipisgit), but for functions. This utility returns zero exit code if a current working directory is a Git repository and non-zero if it's not.


		### Arguments

		1. `deprecated` _Required_ — the name of a deprecated variable. If this variable is set (contains any value), then `"%B$deprecated%b is deprecated.` will be printed.


		This command validates that given program is available for execution. It returns zero exit code if a `command` exists and non-zero if `command` doesn't.

		You can use this utility to check if some program is installed and perform actions conditionally. For example, you can either return an error and exit or continue script's execution.


		## `SPACESHIP_ROOT`

		> Attention! Do not modify the value of this variable! Changing the value may cause the damage of Spaceship installation!


		> Works only for npm at the moment. Please, help us improve this section!

		Package version is shown when repository is a package (contains a `package.json` file). This is the version of the package you are working on, not the version of package manager itself.

Docs for 3.0 (#148) #313

Docs for 3.0 (#148) #313

Conversation

denysdovhan commented Jan 15, 2018 • edited

denysdovhan commented Jan 15, 2018

maximbaz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

salmanulfarzy commented Jan 15, 2018

denysdovhan commented Jan 15, 2018

maximbaz left a comment

Choose a reason for hiding this comment

salmanulfarzy left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

denysdovhan commented Jan 16, 2018

maximbaz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

salmanulfarzy Jan 17, 2018 • edited

Choose a reason for hiding this comment

maximbaz Jan 17, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

salmanulfarzy left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

maximbaz Jan 17, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

salmanulfarzy left a comment • edited

Choose a reason for hiding this comment

denysdovhan commented Jan 17, 2018

denysdovhan commented Jan 15, 2018 •

edited

salmanulfarzy Jan 17, 2018 •

edited

maximbaz Jan 17, 2018 •

edited

maximbaz Jan 17, 2018 •

edited

salmanulfarzy left a comment •

edited