Tweak the docs a bit

bbatsov · Jul 21, 2018 · bf8bc81 · bf8bc81
1 parent 001d013
commit bf8bc81
Show file tree

Hide file tree

Showing 6 changed files with 95 additions and 46 deletions.
diff --git a/doc/configuration.md b/doc/configuration.md
@@ -1,7 +1,13 @@
-#### Indexing method
+In the typical style of Emacs, Projectile is **extremely** configurable.
+Pretty much every aspect of its behaviour can be tweaked or extended.
+
+In this section we'll go over some of the most common things you might
+want to fine-tune to make Projectile fit your workflow better.
+
+## Project indexing method
 
 Projectile has two modes of operation - one is portable and is
-implemented in Emacs Lisp(therefore it's native to Emacs and is known
+implemented in Emacs Lisp (therefore it's *native* to Emacs and is known
 as the `native indexing method`) and the other relies on external
 commands like `find`, `git`, etc to obtain the list of files in a
 project.
@@ -20,13 +26,14 @@ To force the use of external indexing in Windows:
 (setq projectile-indexing-method 'alien)
 ```
 
-This can speed up Projectile in Windows significantly. The disadvantage of this
-method is that it's not well supported on Windows systems. If there's problem,
-you can always use native indexing mode.
+This can speed up Projectile in Windows significantly. The
+disadvantage of this method is that it's not well supported on Windows
+systems, as it requires setting up some Unix utilities there. If
+there's problem, you can always use native indexing mode.
 
-#### Caching
+## Caching
 
-##### Project files
+### Project files
 
 Since indexing a big project is not exactly quick (especially in Emacs
 Lisp), Projectile supports caching of the project's files. The caching
@@ -52,7 +59,7 @@ The project cache is persistent and will be preserved during Emacs restarts.
 You can purge an individual file from the cache with `M-x projectile-purge-file-from-cache` or an
 entire directory with `M-x projectile-purge-dir-from-cache`.
 
-##### File exists cache
+### File exists cache
 
 Projectile does many file existence checks since that is how it identifies a
 project root. Normally this is fine, however in some situations the file system
@@ -82,7 +89,7 @@ needed but possible:
 (setq projectile-file-exists-local-cache-expire (* 5 60))
 ```
 
-#### Using Projectile everywhere
+## Using Projectile everywhere
 
 If you want Projectile to be usable in every directory (even without the presence of project file):
 
@@ -92,7 +99,7 @@ If you want Projectile to be usable in every directory (even without the presenc
 
 This might not be a great idea if you start Projectile in your home folder for instance. :-)
 
-#### Switching projects
+## Switching projects
 
 When running `projectile-switch-project` (<kbd>C-c p p</kbd>) Projectile invokes
 the command specified in `projectile-switch-project-action` (by default it is
@@ -101,7 +108,7 @@ the command specified in `projectile-switch-project-action` (by default it is
 Depending on your personal workflow and habits, you
 may prefer to alter the value of `projectile-switch-project-action`:
 
-###### `projectile-find-file`
+### `projectile-find-file`
 
 This is the default.  With this setting, once you have selected your
 project via Projectile's completion system (see below), you will
@@ -110,13 +117,13 @@ is capable of retrieving files in all sub-projects under the project root,
 such as Git submodules. Currently, only Git is supported. Support for other VCS
 will be added in the future.
 
-###### `projectile-find-file-in-known-projects`
+### `projectile-find-file-in-known-projects`
 
 Similar to `projectile-find-file` but lists all files in all known projects. Since
 the total number of files could be huge, it is beneficial to enable caching for subsequent
 usages.
 
-###### `projectile-find-file-dwim`
+### `projectile-find-file-dwim`
 
 If point is on a filepath, Projectile first tries to search for that
 file in project:
@@ -140,7 +147,7 @@ files with character 'a' in that directory is presented.
 - If it finds nothing, display a list of all files in project for
   selecting.
 
-###### `projectile-dired`
+### `projectile-dired`
 
 ```el
 (setq projectile-switch-project-action #'projectile-dired)
@@ -150,7 +157,7 @@ With this setting, once you have selected your project, the top-level
 directory of the project is immediately opened for you in a dired
 buffer.
 
-###### `projectile-find-dir`
+### `projectile-find-dir`
 
 ```el
 (setq projectile-switch-project-action #'projectile-find-dir)
@@ -169,9 +176,9 @@ want to set
 in order to allow for the occasions where you want to select the
 top-level directory.
 
-#### Completion Options
+## Completion Options
 
-##### Ido
+### Ido
 
 By default Projectile uses `ido` as its completion system. `ido` is
 extremely popular and it is built into Emacs.
@@ -181,15 +188,15 @@ As already noted above if you're going to use the `ido` completion it's
 [flx-ido package](https://github.com/lewang/flx), which provides a much
 more powerful alternative to `ido`'s built-in `flex` matching.
 
-##### Ivy (recommended)
+### Ivy (recommended)
 
 Another completion option is [ivy](https://github.com/abo-abo/swiper):
 
 ```el
 (setq projectile-completion-system 'ivy)
 ```
 
-##### Basic (Emacs's default)
+### Basic (Emacs's default)
 
 If you don't like `ido` and `ivy` you can use regular completion:
 
@@ -199,7 +206,7 @@ If you don't like `ido` and `ivy` you can use regular completion:
 
 You might want to combine default completion with `icomplete-mode` for optimum results.
 
-##### Custom Completion Function
+### Custom Completion Function
 
 You can also set `projectile-completion-system` to a function:
 
@@ -217,16 +224,18 @@ the file name (not including path) and if the file selected is not
 unique, another completion with names relative to project root
 appears.
 
-##### Regenerate tags
+## Regenerate tags
 
 To be able to regenerate a project's tags via `projectile-tags-command`, you
 should install and add to the PATH
 [Exuberant Ctags](http://ctags.sourceforge.net/) instead of a plain ctags, which
 ships with Emacs distribution.
 
-### Adding Custom Project Types
+## Adding Custom Project Types
 
-If a project you are working on is recognized incorrectly or you want to add your own type of projects you can add following to your Emacs initialization code
+If a project you are working on is recognized incorrectly or you want
+to add your own type of projects you can add following to your Emacs
+initialization code
 
 ```el
 (projectile-register-project-type 'npm '("package.json")
@@ -235,6 +244,7 @@ If a project you are working on is recognized incorrectly or you want to add you
 				  :run "npm start"
 				  :test-suffix ".spec")
 ```
+
 What this does is:
 1. add your own type of project, in this case `npm` package.
 2. add a file in a root of the project that helps to identify the type, in this case it is `package.json`.
@@ -257,7 +267,7 @@ Option           | Documentation
 :test-prefix     | A prefix to generate test files names.
 :test-suffix     | A suffix to generate test files names.
 
-### Customizing project root files
+## Customizing project root files
 
 You can set the values of `projectile-project-root-files`,
 `projectile-project-root-files-top-down-recurring`,
@@ -271,15 +281,15 @@ To customize project root files settings:
 M-x customize-group RET projectile RET
 ```
 
-#### File-local project root definitions
+### File-local project root definitions
 
 If you want to override the projectile project root for a specific
 file, you can set the file-local variable `projectile-project-root`. This
 can be useful if you have files within one project that are related to
 a different project (for instance, Org files in one git repo that
 correspond to other projects).
 
-### Storing project settings
+## Storing project settings
 
 From project to project, some things may differ even in the same
 language - coding styles, auto-completion sources, etc.  If you need
@@ -311,7 +321,7 @@ You can also quickly visit or create the `dir-locals-file` with
 
 Here are a few examples of how to use this feature with Projectile.
 
-#### Configuring Projectile's Behavior
+## Configuring Projectile's Behavior
 
 Projectile exposes many variables (via `defcustom`) which allow users
 to customize its behavior.  Directory variables can be used to set
@@ -344,7 +354,7 @@ your project, you could customize it with the following:
 ((nil . ((projectile-project-name . "your-project-name-here"))))
 ```
 
-#### Configure a Project's Compilation, Test and Run commands
+## Configure a Project's Compilation, Test and Run commands
 
 There are a few variables that are intended to be customized via `.dir-locals.el`.
 
@@ -361,7 +371,7 @@ external command or an Emacs Lisp function:
 (setq projectile-test-cmd #'custom-test-function)
 ```
 
-### Idle Timer
+## Idle Timer
 
 Projectile can be configured to run the hook
 `projectile-idle-timer-hook` every time Emacs is in a project and has
@@ -380,7 +390,7 @@ additional functions to the hook using `add-hook`:
 (add-hook 'projectile-idle-timer-hook #'my-projectile-idle-timer-function)
 ```
 
-### Mode line indicator
+## Mode line indicator
 
 By default the minor mode indicator of Projectile appears in the form
 " Projectile[ProjectName]". This is configurable via the custom variable
@@ -390,3 +400,8 @@ By default the minor mode indicator of Projectile appears in the form
 The project name will not appear by default when editing remote files
 (via TRAMP), as recalculating the project name (this is done on every
 keystroke) is a fairly slow operation there.
+
+!!! Warning
+
+    Be extremely careful about what you put here, as all the code in the lighter
+    gets evaluated on every keystroke!
diff --git a/doc/faq.md b/doc/faq.md
@@ -0,0 +1,21 @@
+## Why did you name it Projectile?
+
+I wanted a name that's not as boring as `project.el` and implies that your
+interaction with projects is going to speed up significantly. :-)
+
+## Does Projectile work with TRAMP?
+
+Yeah, it does. I don't use TRAMP myself, however, so I never paid that
+much attention to the TRAMP support. It's mostly community-maintained.
+
+## Why does Projectile violate the rule not to bind keys in the user keymap?
+
+I opted for the `C-c p` prefix fully aware that this violates a very
+established Emacs convention, mostly because it felt practical and
+because pressing `C-c C-p` is not super convenient for many
+people. I've come to regret this decision, though, and it will likely
+be reverted down the road.
+
+## Do you need some help cleanup up all those tickets that have piled up?
+
+Certainly!
diff --git a/doc/index.md b/doc/index.md
@@ -5,17 +5,29 @@ finding project files has a portable implementation written in pure
 Emacs Lisp without the use of GNU `find` (but for performance sake an
 indexing mechanism backed by external commands exists as well).
 
+!!! Tip
+
+    In practical terms the fact that Projectile can index the files in
+    a project without shelling out to `find`, `git` or whatever, means
+    that unlike many similar tools it will work on Windows without any
+    additional setup.
+
 Projectile tries to be practical - portability is great, but if some
 external tools could speed up some task substantially and the tools
 are available, Projectile will leverage them.
 
-This library provides easy project management and navigation. The
+Here's a glimpse of Projectile in action (find file in project using `ido`):
+
+![Projectile Screenshot](screenshots/projectile.png)
+
+Projectile provides easy project management and navigation. The
 concept of a project is pretty basic - just a folder containing
-special file. Currently `git`, `mercurial`, `darcs` and `bazaar` repos
-are considered projects by default. So are `lein`, `maven`, `sbt`,
-`scons`, `rebar` and `bundler` projects. If you want to mark a folder
-manually as a project just create an empty `.projectile` file in
-it. Some of Projectile's features:
+special file. Currently most VCS repos (e.g. `git`, `mercurial`, etc)
+are considered projects by default, as are directories containing
+build tools (e.g. `maven`, `leiningen`, etc) or framework markers
+(e.g. Ruby on Rails). If you want to mark a folder manually as a
+project just create an empty `.projectile` file in it. Some of
+Projectile's features:
 
 * jump to a file in project
 * jump to files at point in project
@@ -36,9 +48,10 @@ it. Some of Projectile's features:
 * run make in a project with a single key chord
 * browse dirty version controlled projects
 
-Here's a glimpse of Projectile in action:
+!!! Info
 
-![Projectile Screenshot](screenshots/projectile.png)
+    A bit of trivia for you - Projectile was my very first open-source project and
+    it has a very special place in my heart!
 
 You can support my work on Projectile via
  [PayPal](https://www.paypal.me/bbatsov),

diff --git a/doc/installation.md b/doc/installation.md
@@ -5,7 +5,9 @@ release). If you're new to Emacs you might want to go through
 [the guided tour of Emacs](https://www.gnu.org/software/emacs/tour/index.html)
 and the built-in tutorial (just press <kbd>C-h t</kbd>).
 
-Projectile officially supports Emacs 25.1+.
+!!! Note
+
+    Projectile officially supports Emacs 25.1+.
 
 ## Installation
 

diff --git a/doc/usage.md b/doc/usage.md
@@ -1,6 +1,4 @@
-## Usage
-
-### Basic setup
+## Basic setup
 
 !!! Note
 
@@ -23,7 +21,7 @@ If you're going to use the default `ido` completion it's
 [flx-ido package](https://github.com/lewang/flx), which provides a much
 more powerful alternative to `ido`'s built-in `flex` matching.
 
-### Interactive Commands
+## Interactive Commands
 
 Here's a list of the interactive Emacs Lisp functions, provided by Projectile:
 
@@ -98,8 +96,7 @@ commands. Here's an example that adds `super-p` as the extra prefix:
 ```
 
 You can also bind the `projectile-command-map` to any other map you'd
-like (including the global keymap).  Prelude does this for its
-[prelude-mode-map](https://github.com/bbatsov/prelude/blob/master/core/prelude-mode.el#L71).
+like (including the global keymap).
 
 For some common commands you might want to take a little shortcut and
 leverage the fairly unused `Super` key (by default `Command` on Mac
@@ -116,7 +113,7 @@ add to your Emacs config:
 Note that the `Super` keybindings are not usable in Windows. Emacs
 Prelude already adds those extra keybindings.
 
-### Ignoring files
+## Ignoring files
 
 If you'd like to instruct Projectile to ignore certain files in a
 project, when indexing it you can do so in the `.projectile` file by

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -9,6 +9,7 @@ pages:
 - Usage: usage.md
 - Configuration: configuration.md
 - Extensions: extensions.md
+- FAQ: faq.md
 - Contributing: contributing.md
 - Support: support.md
 extra_css: