Better documentation

.gitignore

@@ -7,4 +7,6 @@
 /pkg/
 /spec/reports/
 /tmp/
+/html/
+/lib/gemstash/man/
 .*

README.md

@@ -1,161 +1,119 @@
+<!--Automatically generated by Pandoc -->
 [![Build Status](https://travis-ci.org/bundler/gemstash.svg?branch=master)](https://travis-ci.org/bundler/gemstash)
 
 <p align="center"><img src="gemstash.png" /></p>
+What is Gemstash?
+-----------------
 
-## What is Gemstash?
+Gemstash is both a cache for remote servers such as https://rubygems.org, and a private gem source.
 
-Gemstash is both a cache for remote servers such as https://rubygems.org, and a
-private gem source.
+If you are using [bundler](http://bundler.io/) across many machines that have access to a server within your control, you might want to use Gemstash.
 
-If you are using [bundler](http://bundler.io/) across many machines that have
-access to a server within your control, you might want to use Gemstash.
+If you produce gems that you don't want everyone in the world to have access to, you might want to use Gemstash.
 
-If you produce gems that you don't want everyone in the world to have access to,
-you might want to use Gemstash.
+If you frequently bundle the same set of gems across multiple projects, you might want to use Gemstash.
 
-If you frequently bundle the same set of gems across multiple projects, you
-might want to use Gemstash.
+Are you only using gems from https://rubygems.org, and don't bundle the same gems frequently? Well, maybe you don't need Gemstash... yet.
 
-Are you only using gems from https://rubygems.org, and don't bundle the same
-gems frequently? Well, maybe you don't need Gemstash... yet.
-
-## Quickstart Guide
+Quickstart Guide
+----------------
 
 ### Setup
 
-Gemstash is designed to be quick and painless to get set up. By the end of this
-Quickstart Guide, you will be able to bundle stashed gems from public sources
-against a Gemstash server running on your machine.
+Gemstash is designed to be quick and painless to get set up. By the end of this Quickstart Guide, you will be able to bundle stashed gems from public sources against a Gemstash server running on your machine.
 
 Install Gemstash to get started:
 
-```
-$ gem install gemstash
-```
+    $ gem install gemstash
 
-After it is installed, starting Gemstash requires no additional steps. Simply
-start the Gemstash server with the `gemstash` command:
+After it is installed, starting Gemstash requires no additional steps. Simply start the Gemstash server with the `gemstash` command:
 
-```
-$ gemstash start
-```
+    $ gemstash start
 
-You may have noticed that the command finished quickly. This is because Gemstash
-will run the server in the background by default. The server runs on port 9292.
+You may have noticed that the command finished quickly. This is because Gemstash will run the server in the background by default. The server runs on port 9292.
 
 ### Bundling
 
-With the server running, you can bundle against it. Tell Bundler that you want
-to use Gemstash to find gems from RubyGems.org:
+With the server running, you can bundle against it. Tell Bundler that you want to use Gemstash to find gems from RubyGems.org:
 
-```
-$ bundle config mirror.https://rubygems.org http://localhost:9292
-```
+    $ bundle config mirror.https://rubygems.org http://localhost:9292
 
 Now you can create a Gemfile and install gems through Gemstash:
 
-```ruby
+``` ruby
 # ./Gemfile
 source "https://rubygems.org"
 gem "rubywarrior"
 ```
 
-The gems you include should be gems you don't yet have installed,
-otherwise Gemstash will have nothing to stash. Now bundle:
+The gems you include should be gems you don't yet have installed, otherwise Gemstash will have nothing to stash. Now bundle:
 
-```
-$ bundle install --path .bundle
-```
+    $ bundle install --path .bundle
 
-Your Gemstash server has fetched the gems from https://rubygems.org and cached
-them for you! To prove this, you can disable your Internet connection and try
-again. The gem dependencies from https://rubygems.org are cached for 30 minutes,
-so if you bundle again before that, you can successfully bundle without an
-Internet connection:
+Your Gemstash server has fetched the gems from https://rubygems.org and cached them for you! To prove this, you can disable your Internet connection and try again. The gem dependencies from https://rubygems.org are cached for 30 minutes, so if you bundle again before that, you can successfully bundle without an Internet connection:
 
-```
-$ # Disable your Internet first!
-$ rm -rf Gemfile.lock .bundle
-$ bundle
-```
+    $ # Disable your Internet first!
+    $ rm -rf Gemfile.lock .bundle
+    $ bundle
 
 ### Stopping the Server
 
-Once you've finish using your Gemstash server, you can stop it just as easily as
-you started it:
+Once you've finish using your Gemstash server, you can stop it just as easily as you started it:
 
-```
-$ gemstash stop
-```
+    $ gemstash stop
 
-You'll also want to tell Bundler that it can go back to getting gems from
-RubyGems.org directly, instead of going through Gemstash:
+You'll also want to tell Bundler that it can go back to getting gems from RubyGems.org directly, instead of going through Gemstash:
 
-```
-$ bundle config --delete mirror.https://rubygems.org
-```
+    $ bundle config --delete mirror.https://rubygems.org
 
 ### Under the Hood
 
-You might wonder where the gems are stored. After running the commands above,
-you will find a new directory at `~/.gemstash`. This directory holds all the
-cached and private gems. It also has a server log, the database, and
-configuration for Gemstash. If you prefer, you can [point to a different
-directory](docs/config.md#files).
+You might wonder where the gems are stored. After running the commands above, you will find a new directory at `~/.gemstash`. This directory holds all the cached and private gems. It also has a server log, the database, and configuration for Gemstash. If you prefer, you can [point to a different directory](docs/gemstash-customize.7.md#files).
+
+Gemstash uses [SQLite](https://www.sqlite.org/) to store details about private gems. The database will be located in `~/.gemstash`, however you won't see the database appear until you start using private gems. If you prefer, you can [use a different database](docs/gemstash-customize.7.md#database).
+
+Gemstash temporarily caches things like gem dependencies in memory. Anything cached in memory will last for 30 minutes before being retrieved again. You can [use memcached](docs/gemstash-customize.7.md#cache) instead of caching in memory. Gem files are always cached permanently, so bundling with a `Gemfile.lock` with all gems cached will never call out to https://rubygems.org.
 
-Gemstash uses [SQLite](https://www.sqlite.org/) to store details about private
-gems. The database will be located in `~/.gemstash`, however you won't see the
-database appear until you start using private gems. If you prefer, you can [use
-a different database](docs/config.md#database).
+The server you ran is provided via [Puma](http://puma.io/) and [Rack](http://rack.github.io/), however they are not customizable at this point.
 
-Gemstash temporarily caches things like gem dependencies in memory. Anything
-cached in memory will last for 30 minutes before being retrieved again. You can
-[use memcached](docs/config.md#cache) instead of caching in memory. Gem files
-are always cached permanently, so bundling with a `Gemfile.lock` with all gems
-cached will never call out to https://rubygems.org.
+Deep Dive
+---------
 
-The server you ran is provided via [Puma](http://puma.io/) and
-[Rack](http://rack.github.io/), however they are not customizable at this point.
+Deep dive into more subjects:
 
-## Deep Dive
+-   [Private gems](docs/gemstash-private-gems.7.md)
+-   [Multiple gem sources](docs/gemstash-multiple-sources.7.md)
+-   [Using Gemstash as a mirror](docs/gemstash-mirror.7.md)
+-   [Customizing the server (database, storage, caching, and more)](docs/gemstash-customize.7.md)
+-   [Deploying Gemstash](docs/gemstash-deploy.7.md)
+-   [Debugging Gemstash](docs/gemstash-debugging.7.md)
 
-For a deep dive into the following subjects, follow the links:
-* [Private gems](docs/private_gems.md)
-* [Multiple gem sources](docs/multiple_sources.md)
-* [Using Gemstash as a mirror](docs/mirror.md)
-* [Customizing the server (database, storage, caching, and more)](docs/config.md)
-* [Deploying Gemstash](docs/deploy.md)
-* [Debugging Gemstash](docs/debug.md)
+Reference
+---------
 
-## Reference
+An anatomy of various configuration and commands:
 
-For an anatomy of various configuration and commands, follow the links:
-* [Configuration](docs/reference.md#configuration)
-* [Authorize](docs/reference.md#authorize)
-* [Start](docs/reference.md#start)
-* [Stop](docs/reference.md#stop)
-* [Status](docs/reference.md#status)
-* [Setup](docs/reference.md#setup)
-* [Version](docs/reference.md#version)
+-   [Configuration](docs/gemstash-configuration.5.md)
+-   [Authorize](docs/gemstash-authorize.1.md)
+-   [Start](docs/gemstash-start.1.md)
+-   [Stop](docs/gemstash-stop.1.md)
+-   [Status](docs/gemstash-status.1.md)
+-   [Setup](docs/gemstash-setup.1.md)
+-   [Version](docs/gemstash-version.1.md)
 
-To see what has changed in recent versions of Gemstash, see the
-[CHANGELOG](CHANGELOG.md).
+To see what has changed in recent versions of Gemstash, see the [CHANGELOG](https://github.com/bundler/gemstash/blob/master/CHANGELOG.md).
 
-## Development
+Development
+-----------
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run
-`rake` to run RuboCop and the tests. While developing, you can run
-`bin/gemstash` to run Gemstash. You can also run `bin/console` for an
-interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake` to run RuboCop and the tests. While developing, you can run `bin/gemstash` to run Gemstash. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-## Contributing
+Contributing
+------------
 
-Bug reports and pull requests are welcome on GitHub at
-https://github.com/bundler/gemstash. This project is intended to be a safe,
-welcoming space for collaboration, and contributors are expected to adhere to
-the [Contributor Covenant](CODE_OF_CONDUCT.md) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/bundler/gemstash. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](https://github.com/bundler/gemstash/blob/master/CODE_OF_CONDUCT.md) code of conduct.
 
-## License
+License
+-------
 
-The gem is available as open source under the terms of the
-[MIT License](http://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

Rakefile

@@ -2,7 +2,7 @@ require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 require "rubocop/rake_task"
 require_relative "rake/changelog.rb"
-require_relative "rake/table_of_contents.rb"
+require_relative "rake/doc.rb"
 
 RuboCop::RakeTask.new
 
@@ -14,12 +14,14 @@ end
 task spec: :rubocop
 task default: :spec
 
-desc "Generate Table of Contents for certain docs"
-task :toc do
-  TableOfContents.new.run
-end
-
 desc "Update ChangeLog based on commits in master"
 task :changelog do
   Changelog.new.run
 end
+
+desc "Generate markdown, man, text, and html documentation"
+task :doc do
+  Doc.new.run
+end
+
+task build: :doc

docs/gemstash-authorize.1.md

@@ -0,0 +1,34 @@
+<!--Automatically generated by Pandoc -->
+Name
+====
+
+gemstash-authorize - Adds or removes authorization to interact with privately stored gems
+
+Synopsis
+========
+
+`gemstash authorize [permissions] [--remove] [--key SECURE_KEY] [--config-file FILE]`
+
+Description
+===========
+
+Adds or removes authorization to interact with privately stored gems.
+
+Any arguments will be used as specific permissions. Valid permissions include `push`, `yank`, and `unyank`. If no permissions are provided, then all permissions will be granted (including any that may be added in future versions of Gemstash).
+
+Usage
+-----
+
+    gemstash authorize
+    gemstash authorize push yank
+    gemstash authorize yank unyank --key <secure-key>
+    gemstash authorize --remove --key <secure-key>
+
+Options
+=======
+
+-   `--config-file FILE`: Specify the config file to use. If you aren't using the default config file at `~/.gemstash/config.yml`, then you must specify the config file via this option.
+
+-   `--key SECURE_KEY`: Specify the API key to affect. This should be the actual key value, not a name. This option is required when using `--remove` but is optional otherwise. If adding an authorization, using this will either create or update the permissions for the specified API key. If missing, a new API key will always be generated. Note that a key can only have a maximum length of 255 chars.
+
+-   `--remove`: Remove an authorization rather than add or update one. When removing, permission values are not allowed. The `--key <secure-key>` option is required.