Fix #41: Change to subcommand model

* Update documentation and completion for subcommand * Drawback: No support for aliases in argparse 2.7 * Fix #36: Fix Search * Improve search with basic flags, more may follow * Simplify src_hash methods
starcraftman · Nov 18, 2015 · 2e141aa · 2e141aa
1 parent f811374
commit 2e141aa
Show file tree

Hide file tree

Showing 11 changed files with 555 additions and 481 deletions.
diff --git a/DEMO.md b/DEMO.md
@@ -1,119 +1,143 @@
 # Demo
 
 - This demo should take about 5 minutes.
-- Nothing done in this demo will harm your system.
-- Pakit will put all files under `/tmp/pakit`.
-- You should be able to simply copy & paste the following commands into a terminal.
-  These commands are based on my Ubuntu machine.
+- Nothing done in this demo should harm your system.
+- Pakit will install all files under `/tmp/pakit`.
+- Some configs will be written to`~/.pakit.yml` and `~/.pakit/`
+- Copy and paste these commands in order into a terminal.
 
 ## Before Starting
 
-Please see the installation steps & notes in `README.md`.
-You may also find it useful to consule the man page if anything requires clarification.
+Please see the installation steps in the [README.md](https://github.com/starcraftman/pakit/tree/sub_com#install-pakit).
+See the end of the demo for extra information.
 
 ## Run Commands
 
-Run these commands in order to demonstrate Pakit.
-
 **Write User Config**
 
-Writes the default configuration to a file in home, default: `$HOME/.pakit.yml`
-This configuration can be edited by a user to alter Pakit's behaviour.
+The default configuration is written to: `~/.pakit.yml`
+See the man page for a breakdown of the file.
 
 ```bash
-pakit --create-conf
+pakit create-conf
+cat ~/.pakit.yml
 ```
 
-**Install Packages**
+**Install Programs**
+
+To start we will install two programs, `ag` and `tmux`.
 
-Install two packages, the fast grep like program `ag` and the screen replacement
-`tmux` to `pakit.paths.prefix` and link to `pakit.paths.link`. May take a while.
+During the command pakit will:
+- Download source to `pakit.paths.source`
+- Build the source in that dir, then install to `pakit.paths.prefix`
+- Link the installed files to `pakit.paths.links`
 
 ```bash
-pakit --install ag tmux
+pakit install ag tmux
 ```
-
-**Check Programs**
-
-Verify that installed programs work.
-
-1. The `which` command should print out location of binary.
-2. The `ag` command will search your hidden shell files for `export` commands.
+**List Installed Programs**
 
 ```bash
-which ag
-ag --hidden --depth 2 --shell export
+pakit list
 ```
 
-**Remove Package**
+**Check Programs**
+
+Now to verify the installations...
 
-Simple remove, no trace will be left. Only removes tmux.
+1. The `which` command should print out the linked location of `tmux`.
+1. The `ag` command will print matching lines from the config.
 
 ```bash
-pakit --remove tmux
+which tmux
+ag tmp ~/.pakit.yml
 ```
 
-**More Information On Recipe**
+**Remove Program**
 
-Prints out information including description, requirements, repositories to fetch
-source code and any additional notes.
+Now let us remove `tmux` and confirm it is gone.
 
 ```bash
-pakit --display ag vim
+pakit remove tmux
+which tmux
 ```
 
-**List Available Recipes**
+**More Information On A Recipe**
 
-Prints out any recipe Pakit can install.
+Print out information about a recipe, including configured repo and requirements.
 
 ```bash
-pakit --available
+pakit display ag vim
 ```
 
-**List Installed Programs**
+**List Available Recipes**
 
-Prints out recipes that have been installed onto the system.
+Prints out recipes Pakit can install.
+Default recipes can be viewed inside `~/.pakit/base_recipes`
 
 ```bash
-pakit --list
+pakit available
 ```
 
 **Edit Config**
 
-Now to demonstrate configuration options.
-Let us change the repository `ag` builds from `stable` to `unstable`.
-This will force an update since we have specified a different revision to build from.
+Now to demonstrate configuration options I will change the repo `ag` uses.
+By default it downloads and builds a tagged release from the `stable` repo.
+Changing it to `unstable` will force it to rebuild from the latest commit.
 
-Edit your `$HOME/.pakit.yml` file and add the following line at the end. Save and exit.
+Edit `~/.pakit.yml` and add the following section at the end. Save and exit.
 
 ```yaml
 ag:
   repo: unstable
 ```
 
-This newly added `ag` section, overrides the `defaults` section only for the `ag` recipe.
+**Update Recipes**:
 
-**Update Packages**:
+Recipes will be updated when...
+- The configured repo changes.
+- The recipe is tracking a branch with a new commit.
+- The recipe is tracking a tag and it has changed.
+- The recipe is built from an archive and the archive URI has changed.
 
-Updates all recipes on the system.
-If there are new commits on the branch, a tag has been changed or
-the URI/archive has changed it should force a rebuild of the new source.
-At this time, `ag` will be rebuilt from the latest commit to its repository.
+We just changed the repo for `ag` so it will be rebuilt.
 
 ```bash
-pakit --update
+pakit update
 ```
 
 **Verify Update Changed Ag**
 
-This command should list a different hash than before. You may have to scroll up to confirm.
+The hash listed will differ from the one printed before.
 
 ```bash
-pakit --list
+pakit list
 ```
 
+**Search Recipes**
+
+Simple search support is available to find recipes.
+By default the search is case insensitive and matches against recipe names or descriptions.
+
+```bash
+pakit search vim
+```
+
+## Demo Clean Up (Optional)
+
+To remove all files pakit made.
+
+```bash
+rm -rf /tmp/pakit ~/.pakit ~/.pakit.yml
+```
+
+Then just uninstall pakit.
+
 ## More Information
 
-- pakit --help
-- man pakit
-- pydoc pakit
+More information is available is available from ...
+
+- `pakit --help`
+- `man pakit`
+-  man pakit_recipes
+- `pydoc pakit`
diff --git a/DESIGN.md b/DESIGN.md
@@ -1,47 +1,22 @@
-## Expected Command Line
+## First Command Line
 
-- `pakit --install tmux ag`       -- Install several programs
-- `pakit --update`                -- Update local programs
-- `pakit --remove tmux`           -- Remove program
-- `pakit --list`                  -- List installed programs
-- `pakit --available`             -- List ALL available formula
-- `pakit --search lib`            -- Display matching avilable recipes
-- `pakit --conf ./a.yaml -i ag`   -- Override default config
-- `pakit --display vim ag`        -- Display package information
-- `pakit --relink`                -- Relink all programs
+- `pakit install tmux ag`       -- Install several programs
+- `pakit update`                -- Update local programs
+- `pakit remove tmux`           -- Remove program
+- `pakit list`                  -- List installed programs
+- `pakit available`             -- List ALL available formula
+- `pakit search lib`            -- Display matching avilable recipes
+- `pakit --conf a.yaml list`    -- Override default config
+- `pakit display vim ag`        -- Display package information
+- `pakit relink`                -- Relink all programs
 
-Short opts in order: -i -u -r -l -a -s -c -d
+Short opts: No longer supported with subcommand model.
 
 ## Configuration
 
-File config by a YAML file, default at `$HOME/.pakit.yml`.
-
-```yaml
-# Default options passed to all recipes self.opts, can be overwridden by specific opts.
-defaults:
-  repo: unstable
-paths:
-  # Where all builds will go, each under /tmp/pakit/builds/recipe.name folder
-  prefix: /tmp/pakit/builds
-  # Where builds will link to, should go on your PATH
-  link: /tmp/pakit/links
-  # Where source code will go
-  source: /tmp/pakit/src
-  # User can define a series of folders with recipes
-  recipes:
-    - path1
-    - path2
-log:
-  enabled: true
-  file: /tmp/pakit/main.log
-# Example of specific options, for recipe in 'ag.py'
-# Note that here ag will be built with 'stable' repo instead of default.
-ag:
-  repo: stable
-  # These two options will be available in build/verify funcs via self.opts.
-  option_1: hello
-  option_2: world
-```
+See one of the following for up to date configuration:
+- pydoc pakit.conf
+- man pakit
 
 ## Recipe Specification
 
@@ -55,35 +30,12 @@ Parts of standard recipe:
 - description: Short 1 line description. First non-empty line of __doc__.
 - more_info: Long as you want. second non-empty line of __doc__ to end.
 - homepage: Where people can get information on the project.
-- repos: A dict of possible source downloaders.
+- repos: A dict of possible source downloaders. See pakit.shell.Fetchable and subclasses.
 - build(): A function that builds the source selectable by config.
 - verify(): A function that uses `assert` statements to verify build.
 
-Example:
-```py
-""" Formula for building ag """
-from pakit import Git, Recipe
-
-
-class Ag(Recipe):
-    """ Grep like tool optimized for speed """
-    def __init__(self):
-        super(Ag, self).__init__()
-        self.src = 'https://github.com/ggreer/the_silver_searcher'
-        self.homepage = self.src
-        self.repos = {
-            'stable': Git(self.src, tag='0.30.0'),
-            'unstable': Git(self.src),
-        }
-
-    def build(self):
-        self.cmd('./build.sh --prefix {prefix}')
-        self.cmd('make install')
-
-    def verify(self):
-        lines = self.cmd('{link}/bin/ag --version')
-        assert lines[0].find('ag version') != -1
-```
+Example recipe with heavy documentation available with base_recipes.
+Please see ~/.pakit/base_recipes/example.py for more details.
 
 ## Dependencies: