mirror of
https://github.com/pyenv/pyenv.git
synced 2024-11-21 20:47:00 -05:00
Use mdtoc for the readme
This commit is contained in:
Sam Stephenson
parent
7c8da88df6
commit
066d63c0df
4 changed files with 334 additions and 37 deletions
92
README.md
92
README.md
|
|
@ -36,7 +36,18 @@ tools that do one thing well.
|
|||
of executing arbitrary code, rbenv reads just the version name
|
||||
from each project. There's nothing to "trust."
|
||||
|
||||
## How It Works
|
||||
* [1 How It Works](#section_1)
|
||||
* [2 Installation](#section_2)
|
||||
* [3 Usage](#section_3)
|
||||
* [3.1 set-default](#section_3.1)
|
||||
* [3.2 set-local](#section_3.2)
|
||||
* [3.3 versions](#section_3.3)
|
||||
* [3.4 version](#section_3.4)
|
||||
* [3.5 rehash](#section_3.5)
|
||||
* [4 Contributing](#section_4)
|
||||
* [4.1 License](#section_4.1)
|
||||
|
||||
## <a name="section_1">1</a> How It Works
|
||||
|
||||
rbenv operates on the per-user directory `~/.rbenv`. Version names in
|
||||
rbenv correspond to subdirectories of `~/.rbenv/versions`. For
|
||||
|
|
@ -56,7 +67,7 @@ and then execute the corresponding binary.
|
|||
Because of the simplicity of the shim approach, all you need to use
|
||||
rbenv is `~/.rbenv/shims` in your `$PATH`.
|
||||
|
||||
## Installation
|
||||
## <a name="section_2">2</a> Installation
|
||||
|
||||
rbenv is a young project, so for now you must install it from source.
|
||||
|
||||
|
|
@ -103,55 +114,62 @@ when installing a gem that provides a binary).
|
|||
|
||||
$ rbenv rehash
|
||||
|
||||
## Usage
|
||||
## <a name="section_3">3</a> Usage
|
||||
|
||||
Like `git`, the `rbenv` command delegates to subcommands based on its
|
||||
first argument. The most common subcommands are:
|
||||
|
||||
* **set-default** — sets the default version of Ruby to be used in all
|
||||
shells by writing the version name to the `~/.rbenv/default`
|
||||
file. This version can be overridden by a per-project
|
||||
`.rbenv-version` file, or by setting the `RBENV_VERSION`
|
||||
environment variable.
|
||||
### <a name="section_3.1">3.1</a> set-default
|
||||
|
||||
$ rbenv set-default 1.9.2-p290
|
||||
Sets the default version of Ruby to be used in all shells by writing
|
||||
the version name to the `~/.rbenv/default` file. This version can be
|
||||
overridden by a per-project `.rbenv-version` file, or by setting the
|
||||
`RBENV_VERSION` environment variable.
|
||||
|
||||
The special version name `system` tells rbenv to use the system
|
||||
Ruby (detected by searching your `$PATH`).
|
||||
$ rbenv set-default 1.9.2-p290
|
||||
|
||||
* **set-local** — sets a local per-project Ruby version by writing the
|
||||
version name to an `.rbenv-version` file in the current
|
||||
directory. This version overrides the default, and can be
|
||||
overridden itself by setting the `RBENV_VERSION` environment
|
||||
variable.
|
||||
The special version name `system` tells rbenv to use the system Ruby
|
||||
(detected by searching your `$PATH`).
|
||||
|
||||
$ rbenv set-local rbx-1.2.4
|
||||
### <a name="section_3.2">3.2</a> set-local
|
||||
|
||||
* **versions** — lists all Ruby versions known to rbenv, and shows an
|
||||
asterisk next to the currently active version.
|
||||
Sets a local per-project Ruby version by writing the version name to
|
||||
an `.rbenv-version` file in the current directory. This version
|
||||
overrides the default, and can be overridden itself by setting the
|
||||
`RBENV_VERSION` environment variable.
|
||||
|
||||
$ rbenv versions
|
||||
1.8.7-p352
|
||||
1.9.2-p290
|
||||
* 1.9.3-preview1 (set by /Users/sam/.rbenv/default)
|
||||
jruby-1.6.3
|
||||
rbx-1.2.4
|
||||
ree-1.8.7-2011.03
|
||||
$ rbenv set-local rbx-1.2.4
|
||||
|
||||
* **version** — displays the currently active Ruby version, along with
|
||||
information on how it was set.
|
||||
### <a name="section_3.3">3.3</a> versions
|
||||
|
||||
$ rbenv version
|
||||
1.8.7-p352 (set by /Volumes/37signals/basecamp/.rbenv-version)
|
||||
Lists all Ruby versions known to rbenv, and shows an asterisk next to
|
||||
the currently active version.
|
||||
|
||||
* **rehash** — installs shims for all Ruby binaries known to rbenv
|
||||
(i.e., `~/.rbenv/versions/*/bin/*`). Run this command after you
|
||||
install a new version of Ruby, or install a gem that provides
|
||||
binaries.
|
||||
$ rbenv versions
|
||||
1.8.7-p352
|
||||
1.9.2-p290
|
||||
* 1.9.3-preview1 (set by /Users/sam/.rbenv/default)
|
||||
jruby-1.6.3
|
||||
rbx-1.2.4
|
||||
ree-1.8.7-2011.03
|
||||
|
||||
$ rbenv rehash
|
||||
### <a name="section_3.4">3.4</a> version
|
||||
|
||||
## Contributing
|
||||
Displays the currently active Ruby version, along with information on
|
||||
how it was set.
|
||||
|
||||
$ rbenv version
|
||||
1.8.7-p352 (set by /Volumes/37signals/basecamp/.rbenv-version)
|
||||
|
||||
### <a name="section_3.5">3.5</a> rehash
|
||||
|
||||
Installs shims for all Ruby binaries known to rbenv (i.e.,
|
||||
`~/.rbenv/versions/*/bin/*`). Run this command after you install a new
|
||||
version of Ruby, or install a gem that provides binaries.
|
||||
|
||||
$ rbenv rehash
|
||||
|
||||
## <a name="section_4">4</a> Contributing
|
||||
|
||||
The rbenv source code is [hosted on
|
||||
GitHub](https://github.com/sstephenson/rbenv). It's clean, modular,
|
||||
|
|
@ -160,7 +178,7 @@ and easy to understand, even if you're not a shell hacker.
|
|||
Please feel free to submit pull requests and file bugs on the [issue
|
||||
tracker](https://github.com/sstephenson/rbenv/issues).
|
||||
|
||||
## License
|
||||
### <a name="section_4.1">4.1</a> License
|
||||
|
||||
(The MIT license)
|
||||
|
||||
|
|
|
|||
193
doc/README.mdtoc
Normal file
193
doc/README.mdtoc
Normal file
|
|
@ -0,0 +1,193 @@
|
|||
# Simple Ruby Version Management: rbenv
|
||||
|
||||
<img src="http://cloud.github.com/downloads/sstephenson/rbenv/rbenv.png" width="894" height="464">
|
||||
|
||||
rbenv lets you easily switch between multiple versions of Ruby. It's
|
||||
simple, unobtrusive, and follows the UNIX tradition of single-purpose
|
||||
tools that do one thing well.
|
||||
|
||||
### rbenv _does…_
|
||||
|
||||
* Let you **change the default Ruby version** on a per-user basis.
|
||||
* Provide support for **per-project Ruby versions**.
|
||||
* Allow you to **override the Ruby version** with an environment
|
||||
variable.
|
||||
|
||||
### In contrast with rvm, rbenv _does not…_
|
||||
|
||||
* **Need to be loaded into your shell.** Instead, rbenv's shim
|
||||
approach works by adding a directory to your `$PATH`.
|
||||
* **Override shell commands like `cd`.** That's just obnoxious!
|
||||
* **Have a configuration file.** There's nothing to configure except
|
||||
which version of Ruby you want to use.
|
||||
* **Install Ruby.** You can build and install Ruby yourself, or use
|
||||
[ruby-build](https://github.com/sstephenson/ruby-build.git) to
|
||||
automate the process.
|
||||
* **Manage gemsets.** [Bundler](http://gembundler.com/) is a better
|
||||
way to manage application dependencies. If you have projects that
|
||||
are not yet using Bundler you can install the
|
||||
[rbenv-gemset](https://github.com/jamis/rbenv-gemset) plugin.
|
||||
* **Require changes to Ruby libraries for compatibility.** The
|
||||
simplicity of rbenv means as long as it's in your `$PATH`,
|
||||
[nothing](https://rvm.beginrescueend.com/integration/bundler/)
|
||||
[else](https://rvm.beginrescueend.com/integration/capistrano/)
|
||||
needs to know about it.
|
||||
* **Prompt you with warnings when you switch to a project.** Instead
|
||||
of executing arbitrary code, rbenv reads just the version name
|
||||
from each project. There's nothing to "trust."
|
||||
|
||||
## How It Works ##
|
||||
|
||||
rbenv operates on the per-user directory `~/.rbenv`. Version names in
|
||||
rbenv correspond to subdirectories of `~/.rbenv/versions`. For
|
||||
example, you might have `~/.rbenv/versions/1.8.7-p354` and
|
||||
`~/.rbenv/versions/1.9.3-preview1`.
|
||||
|
||||
Each version is a working tree with its own binaries, like
|
||||
`~/.rbenv/versions/1.8.7-p354/bin/ruby` and
|
||||
`~/.rbenv/versions/1.9.3-preview1/irb`. rbenv makes _shim binaries_
|
||||
for every such binary across all installed versions of Ruby.
|
||||
|
||||
These shims are simple wrapper scripts that live in `~/.rbenv/shims`
|
||||
and detect which Ruby version you want to use. They insert the
|
||||
directory for the selected version at the beginning of your `$PATH`
|
||||
and then execute the corresponding binary.
|
||||
|
||||
Because of the simplicity of the shim approach, all you need to use
|
||||
rbenv is `~/.rbenv/shims` in your `$PATH`.
|
||||
|
||||
## Installation ##
|
||||
|
||||
rbenv is a young project, so for now you must install it from source.
|
||||
|
||||
**Compatibility note**: rbenv is _incompatible_ with rvm. Things will
|
||||
appear to work until you try to install a gem. The problem is that
|
||||
rvm actually overrides the `gem` command with a shell function!
|
||||
Please remove any references to rvm before using rbenv.
|
||||
|
||||
1. Check out rbenv into `~/.rbenv`.
|
||||
|
||||
$ cd
|
||||
$ git clone git://github.com/sstephenson/rbenv.git .rbenv
|
||||
|
||||
2. Add `~/.rbenv/bin` to your `$PATH` for access to the `rbenv`
|
||||
command-line utility.
|
||||
|
||||
$ echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> .bash_profile
|
||||
|
||||
3. Add rbenv's shims directory to your `$PATH` and set up Bash
|
||||
autocompletion. (If you prefer not to load rbenv in your shell, you
|
||||
can manually add `$HOME/.rbenv/shims` to your path in step 2.)
|
||||
|
||||
$ echo 'eval "$(rbenv init -)"' >> .bash_profile
|
||||
|
||||
4. Restart your shell. You can now begin using rbenv.
|
||||
|
||||
$ exec
|
||||
|
||||
5. Install Ruby versions into `~/.rbenv/versions`. For example, to
|
||||
install Ruby 1.9.2-p290, download and unpack the source, then run:
|
||||
|
||||
$ ./configure --prefix=~/.rbenv/versions/1.9.2-p290
|
||||
$ make
|
||||
$ make install
|
||||
|
||||
The [ruby-build](https://github.com/sstephenson/ruby-build)
|
||||
project simplifies this process to a single command:
|
||||
|
||||
$ ruby-build 1.9.2-p290 ~/.rbenv/versions/1.9.2-p290
|
||||
|
||||
6. Rebuild the shim binaries. You should do this any time you install
|
||||
a new Ruby binary (for example, when installing a new Ruby version, or
|
||||
when installing a gem that provides a binary).
|
||||
|
||||
$ rbenv rehash
|
||||
|
||||
## Usage ##
|
||||
|
||||
Like `git`, the `rbenv` command delegates to subcommands based on its
|
||||
first argument. The most common subcommands are:
|
||||
|
||||
### set-default ###
|
||||
|
||||
Sets the default version of Ruby to be used in all shells by writing
|
||||
the version name to the `~/.rbenv/default` file. This version can be
|
||||
overridden by a per-project `.rbenv-version` file, or by setting the
|
||||
`RBENV_VERSION` environment variable.
|
||||
|
||||
$ rbenv set-default 1.9.2-p290
|
||||
|
||||
The special version name `system` tells rbenv to use the system Ruby
|
||||
(detected by searching your `$PATH`).
|
||||
|
||||
### set-local ###
|
||||
|
||||
Sets a local per-project Ruby version by writing the version name to
|
||||
an `.rbenv-version` file in the current directory. This version
|
||||
overrides the default, and can be overridden itself by setting the
|
||||
`RBENV_VERSION` environment variable.
|
||||
|
||||
$ rbenv set-local rbx-1.2.4
|
||||
|
||||
### versions ###
|
||||
|
||||
Lists all Ruby versions known to rbenv, and shows an asterisk next to
|
||||
the currently active version.
|
||||
|
||||
$ rbenv versions
|
||||
1.8.7-p352
|
||||
1.9.2-p290
|
||||
* 1.9.3-preview1 (set by /Users/sam/.rbenv/default)
|
||||
jruby-1.6.3
|
||||
rbx-1.2.4
|
||||
ree-1.8.7-2011.03
|
||||
|
||||
### version ###
|
||||
|
||||
Displays the currently active Ruby version, along with information on
|
||||
how it was set.
|
||||
|
||||
$ rbenv version
|
||||
1.8.7-p352 (set by /Volumes/37signals/basecamp/.rbenv-version)
|
||||
|
||||
### rehash ###
|
||||
|
||||
Installs shims for all Ruby binaries known to rbenv (i.e.,
|
||||
`~/.rbenv/versions/*/bin/*`). Run this command after you install a new
|
||||
version of Ruby, or install a gem that provides binaries.
|
||||
|
||||
$ rbenv rehash
|
||||
|
||||
## Contributing ##
|
||||
|
||||
The rbenv source code is [hosted on
|
||||
GitHub](https://github.com/sstephenson/rbenv). It's clean, modular,
|
||||
and easy to understand, even if you're not a shell hacker.
|
||||
|
||||
Please feel free to submit pull requests and file bugs on the [issue
|
||||
tracker](https://github.com/sstephenson/rbenv/issues).
|
||||
|
||||
### License ###
|
||||
|
||||
(The MIT license)
|
||||
|
||||
Copyright (c) 2011 Sam Stephenson
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining
|
||||
a copy of this software and associated documentation files (the
|
||||
"Software"), to deal in the Software without restriction, including
|
||||
without limitation the rights to use, copy, modify, merge, publish,
|
||||
distribute, sublicense, and/or sell copies of the Software, and to
|
||||
permit persons to whom the Software is furnished to do so, subject to
|
||||
the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be
|
||||
included in all copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||||
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
||||
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
||||
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
||||
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
||||
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
4
doc/build
Executable file
4
doc/build
Executable file
|
|
@ -0,0 +1,4 @@
|
|||
#!/bin/sh -e
|
||||
|
||||
ruby mdtoc.rb README.mdtoc > ../README.md
|
||||
|
||||
82
doc/mdtoc.rb
Normal file
82
doc/mdtoc.rb
Normal file
|
|
@ -0,0 +1,82 @@
|
|||
#!/usr/bin/env ruby
|
||||
|
||||
# A little Markdown filter that scans your document for headings,
|
||||
# numbers them, adds anchors, and inserts a table of contents.
|
||||
#
|
||||
# To use it, make sure the headings you want numbered and linked are
|
||||
# in this format:
|
||||
#
|
||||
# ### Title ###
|
||||
#
|
||||
# I.e. they must have an equal number of octothorpes around the title
|
||||
# text. (In Markdown, `#` means `h1`, `##` means `h2`, and so on.)
|
||||
# The table of contents will be inserted before the first such
|
||||
# heading.
|
||||
#
|
||||
# Released into the public domain.
|
||||
# Sam Stephenson <sstephenson@gmail.com>
|
||||
# 2011-04-30
|
||||
|
||||
def mdtoc(markdown)
|
||||
titles = []
|
||||
lines = markdown.split($/)
|
||||
start = nil
|
||||
|
||||
# First pass: Scan the Markdown source looking for titles of the
|
||||
# format: `### Title ###`. Record the line number, header level
|
||||
# (number of octothorpes), and text of each matching title.
|
||||
lines.each_with_index do |line, line_no|
|
||||
if line.match(/^(\#{1,6})\s+(.+?)\s+\1$/)
|
||||
titles << [line_no, $1.length, $2]
|
||||
start ||= line_no
|
||||
end
|
||||
end
|
||||
|
||||
last_section = nil
|
||||
last_level = nil
|
||||
|
||||
# Second pass: Iterate over all matched titles and compute their
|
||||
# corresponding section numbers. Then replace the titles with
|
||||
# annotated anchors.
|
||||
titles.each do |title_info|
|
||||
line_no, level, text = title_info
|
||||
|
||||
if last_section
|
||||
section = last_section.dup
|
||||
|
||||
if last_level < level
|
||||
section << 1
|
||||
else
|
||||
(last_level - level).times { section.pop }
|
||||
section[-1] += 1
|
||||
end
|
||||
else
|
||||
section = [1]
|
||||
end
|
||||
|
||||
name = section.join(".")
|
||||
lines[line_no] = %(#{"#" * level} <a name="section_#{name}">#{name}</a> #{text})
|
||||
|
||||
title_info << section
|
||||
last_section = section
|
||||
last_level = level
|
||||
end
|
||||
|
||||
# Third pass: Iterate over matched titles once more to produce the
|
||||
# table of contents. Then insert it immediately above the first
|
||||
# matched title.
|
||||
if start
|
||||
toc = titles.map do |(line_no, level, text, section)|
|
||||
name = section.join(".")
|
||||
%(#{" " * (section.length * 3)}* [#{name} #{text}](#section_#{name}))
|
||||
end + [""]
|
||||
|
||||
lines.insert(start, *toc)
|
||||
end
|
||||
|
||||
lines.join("\n")
|
||||
end
|
||||
|
||||
if __FILE__ == $0
|
||||
puts mdtoc($<.read)
|
||||
end
|
||||
Loading…
Reference in a new issue