From 6629abd91f9d2c542497754f8d19c75cddd4a757 Mon Sep 17 00:00:00 2001
From: tesladethray <tesladethray@gmail.com>
Date: Fri, 12 Feb 2016 15:51:11 -0800
Subject: [PATCH] Updated documentation and doc-making script

---
 docs/Helpers/AuthHelper.md                    |  98 ++++++
 docs/Helpers/InputHelper.md                   | 313 ++++++++++++++++++
 docs/Helpers/LaunchHelper.md                  |  34 ++
 docs/Helpers/TemplateHelper.md                |  29 ++
 docs/Helpers/TerminusHelper.md                |  14 +
 .../OrganizationUserMemberships.md            |  18 +-
 docs/Models/Environment.md                    |  21 ++
 docs/Models/Organization.md                   |  12 +
 docs/Models/OrganizationUserMembership.md     |  12 +
 docs/Models/Site.md                           |  18 +-
 utils/make-docs.php                           |  23 +-
 11 files changed, 571 insertions(+), 21 deletions(-)
 create mode 100644 docs/Helpers/AuthHelper.md
 create mode 100644 docs/Helpers/InputHelper.md
 create mode 100644 docs/Helpers/LaunchHelper.md
 create mode 100644 docs/Helpers/TemplateHelper.md
 create mode 100644 docs/Helpers/TerminusHelper.md

diff --git a/docs/Helpers/AuthHelper.md b/docs/Helpers/AuthHelper.md
new file mode 100644
index 000000000..ea2029c66
--- /dev/null
+++ b/docs/Helpers/AuthHelper.md
@@ -0,0 +1,98 @@
+# Terminus\Helpers\AuthHelper
+
+### __construct
+##### Description:
+    Object constructor
+
+##### Parameters:
+    [array] $options Options and dependencies for this helper
+
+##### Return:
+    [AuthHelper]
+
+---
+
+### ensureLogin
+##### Description:
+    Ensures the user is logged in or errs.
+
+##### Return:
+    [bool] Always true
+
+##### Throws:
+    TerminusException
+
+---
+
+### getMachineTokenCreationUrl
+##### Description:
+    Generates the URL string for where to create a machine token
+
+##### Return:
+    [string]
+
+---
+
+### getOnlySavedToken
+##### Description:
+    Gets the only saved token or returns false
+
+##### Return:
+    [bool|string]
+
+---
+
+### loggedIn
+##### Description:
+    Checks to see if the current user is logged in
+
+##### Return:
+    [bool] True if the user is logged in
+
+---
+
+### logInViaMachineToken
+##### Description:
+    Execute the login based on a machine token
+
+##### Parameters:
+    [string[]] $args Elements as follow:
+    -string token Machine token to initiate login with
+    -string email Email address to locate token with
+
+##### Return:
+    [bool] True if login succeeded
+
+##### Throws:
+    TerminusException
+
+---
+
+### logInViaUsernameAndPassword
+##### Description:
+    Execute the login via email/password
+
+##### Parameters:
+    [string] $email    Email address associated with a Pantheon account
+    [string] $password Password for the account
+
+##### Return:
+    [bool] True if login succeeded
+
+##### Throws:
+    TerminusException
+
+---
+
+### tokenExistsForEmail
+##### Description:
+    Checks to see whether the email has been set with a machine token
+
+##### Parameters:
+    [string] $email Email address to check for
+
+##### Return:
+    [bool]
+
+---
+
diff --git a/docs/Helpers/InputHelper.md b/docs/Helpers/InputHelper.md
new file mode 100644
index 000000000..43f3409f2
--- /dev/null
+++ b/docs/Helpers/InputHelper.md
@@ -0,0 +1,313 @@
+# Terminus\Helpers\InputHelper
+
+### backup
+##### Description:
+    Produces a menu to select a backup
+
+##### Parameters:
+    [array] $arg_options Elements as follow:
+    -string label   Prompt for STDOUT
+    -array  backups Array of Backup objects
+
+##### Return:
+    [\stdClass] An object representing the backup desired
+
+##### Throws:
+    TerminusException
+
+---
+
+### backupElement
+##### Description:
+    Produces a menu to narrow down an element selection
+
+##### Parameters:
+    [array] $arg_options Elements as follow:
+    -array  args    Arguments given via param
+    -string key     Args key to search for
+    -string label   Prompt for STDOUT
+    -array  choices Menu options for the user
+
+##### Return:
+    [string] Either the selection, its index, or the default
+
+##### Throws:
+    TerminusException
+
+---
+
+### day
+##### Description:
+    Facilitates the selection of a day of the week
+
+##### Parameters:
+    [array] $arg_options Elements as follow:
+    -array  args    Arguments given via param
+    -string key     Args key to search for
+    -string label   Prompt for STDOUT
+    -array  choices Menu options for the user, may be a collection
+
+##### Return:
+    [int]
+
+---
+
+### env
+##### Description:
+    Produces a menu with the given attributes
+
+##### Parameters:
+    [array] $arg_options Elements as follow:
+    -array  args    Arguments given via param
+    -string key     Args key to search for
+    -string label   Prompt for STDOUT
+    -array  choices Menu options for the user, may be a collection
+    -Site   site    Site object to gather environment choices from
+
+##### Return:
+    [string] Either the selection, its index, or the default
+
+---
+
+### getNullInputs
+##### Description:
+    Returns the null input list
+
+##### Return:
+    [string[]]
+
+---
+
+### menu
+##### Description:
+    Produces a menu with the given attributes
+
+##### Parameters:
+    [array] $arg_options Elements as follow:
+    -bool   autoselect_solo Automatically selects the only given option
+    -array  choices         Menu options for the user
+    -mixed  default         Given as null option in the menu
+    -string message         Prompt printed to STDOUT
+    -bool   return_value    If true, returns selection. False, the index
+
+##### Return:
+    [string] Either the selection, its index, or the default
+
+---
+
+### optional
+##### Description:
+    Returns $args[$key] if exists, $default otherwise
+
+##### Parameters:
+    [array] $arg_options Elements as follow:
+    -string key     Index of arg to return
+    -array  choices    Args to search for key
+    -mixed  default Returned if $args[$key] DNE
+
+##### Return:
+    [mixed] Either $args[$key] or $default
+
+---
+
+### orgId
+##### Description:
+    Input helper that provides interactive menu to select org name
+
+##### Parameters:
+    [array] $arg_options Elements as follow:
+    -array  args       The args passed in from argv
+    -string key        Args key to search for
+    -string default    Returned if arg and stdin fail in interactive
+    -array  allow_none True to permit no selection to be an option
+
+##### Return:
+    [string] ID of selected organization
+
+##### Throws:
+    TerminusException
+
+---
+
+### orgMember
+##### Description:
+    Input helper to aid in selecting an organizational member
+
+##### Parameters:
+    [array] $arg_options Elements as follow:
+    -array        args            The args passed in from argv
+    -bool         autoselect_solo Automatically selects the only member
+    -bool         can_pick_self   True allows self-selection if using org
+    -array        choices         Args to search for key
+    -string       key             Args key to search for
+    -string       message         Prompt to STDOUT
+    -Organization org             Org to generate choices from
+
+##### Return:
+    [string|OrganizationUserMembership]
+
+##### Throws:
+    TerminusException
+
+---
+
+### orgName
+##### Description:
+    Input helper that provides interactive menu to select org name
+
+##### Parameters:
+    [array] $arg_options Elements as follow:
+    -array  args The args passed in from argv
+    -string key  Args key to search for
+
+##### Return:
+    [string] Site name
+
+---
+
+### orgRole
+##### Description:
+    Helper function to get an organizational team role
+
+##### Parameters:
+    [array] $arg_options Elements as follow:
+    -array  args Argument array passed from commands
+    -string message    Prompt to STDOUT
+
+##### Return:
+    [string] Name of role
+
+---
+
+### prompt
+##### Description:
+    Prompt the user for input
+
+##### Parameters:
+    [array] $arg_options Elements as follow:
+    -string message Message to give at prompt
+    -mixed  default Returned if user does not select a valid option
+
+##### Return:
+    [string]
+
+##### Throws:
+    TerminusException
+
+---
+
+### promptSecret
+##### Description:
+    Gets input from STDIN silently
+    By: Troels Knak-Nielsen
+    From: http://www.sitepoint.com/interactive-cli-password-prompt-in-php/
+
+##### Parameters:
+    [array] $arg_options Elements as follow:
+    -string message Message to give at prompt
+    -mixed  default Returned if user does not select a valid option
+
+##### Return:
+    [string]
+
+##### Throws:
+    TerminusException
+
+---
+
+### siteRole
+##### Description:
+    Helper function to get site team role
+
+##### Parameters:
+    [array] $arg_options Elements as follow:
+    -array  args Argument array passed from commands
+    -string message    Prompt to STDOUT
+
+##### Return:
+    [string] Name of role
+
+---
+
+### serviceLevel
+##### Description:
+    Helper function to select a service level
+
+##### Parameters:
+    [array] $arg_options Elements as follow:
+    -array  args    The args passed in from argv
+    -string key     Args key to search for
+    -string message    Prompt to STDOUT
+
+##### Return:
+    [string]
+
+---
+
+### siteName
+##### Description:
+    Input helper that provides interactive site list
+
+##### Parameters:
+    [array] $arg_options Elements as follow:
+    -array  args    The args passed in from argv
+    -string key     Args key to search for
+    -string message Prompt for STDOUT
+
+##### Return:
+    [string] Site name
+
+---
+
+### string
+##### Description:
+    Returns $args[key] if exists, then STDIN, then $default
+
+##### Parameters:
+    [array] $arg_options Elements as follow:
+    -array  args    Args already input
+    -string key     Key for searched-for argument
+    -string message Prompt printed to STDOUT
+    -mixed  default Returns if no other choice
+
+##### Return:
+    [string] Either $args[$key], $default, or string from prompt
+
+---
+
+### upstream
+##### Description:
+    Helper function to select valid upstream
+
+##### Parameters:
+    [array] $arg_options Elements as follow:
+    -array  args Args to parse value from
+    -string key  Index to search for in args
+    -bool   exit If true, throw error when no value is found
+
+##### Return:
+    [Upstream]
+
+##### Throws:
+    TerminusException
+
+---
+
+### workflow
+##### Description:
+    Helper function to select Site Workflow
+
+##### Parameters:
+    [array] $arg_options Elements as follow:
+    -Workflow[] workflows Array of workflows to list
+    -array      args      Args to parse value from
+    -string     key       Index to search for in args
+
+##### Return:
+    [Workflow]
+
+##### Throws:
+    TerminusException
+
+---
+
diff --git a/docs/Helpers/LaunchHelper.md b/docs/Helpers/LaunchHelper.md
new file mode 100644
index 000000000..9f2b9a54d
--- /dev/null
+++ b/docs/Helpers/LaunchHelper.md
@@ -0,0 +1,34 @@
+# Terminus\Helpers\LaunchHelper
+
+### launch
+##### Description:
+    Launch an external process that takes over I/O.
+
+##### Parameters:
+    [array] $arg_options Elements as follow:
+    -string command         Command to call
+    -array  descriptor_spec How PHP passes descriptor to child process
+    -bool   exit_on_error   True to exit if the command returns error
+
+##### Return:
+    [int]   The command exit status
+
+---
+
+### launchSelf
+##### Description:
+    Launch another Terminus command using the runtime arguments for the
+    current process
+
+##### Parameters:
+    [array] $arg_options Elements as follow:
+    -string command       Command to call
+    -array  args          Positional arguments to use
+    -array  assoc_args    Associative arguments to use
+    -bool   exit_on_error True to exit if the command returns error
+
+##### Return:
+    [int]   The command exit status
+
+---
+
diff --git a/docs/Helpers/TemplateHelper.md b/docs/Helpers/TemplateHelper.md
new file mode 100644
index 000000000..82d049e7d
--- /dev/null
+++ b/docs/Helpers/TemplateHelper.md
@@ -0,0 +1,29 @@
+# Terminus\Helpers\TemplateHelper
+
+### __construct
+##### Description:
+    TemplateHelper constructor.
+
+##### Parameters:
+    [array] $options Options and dependencies for this helper
+
+##### Return:
+    [TerminusHelper] $this
+
+---
+
+### render
+##### Description:
+    Renders the data using the given options.
+
+##### Parameters:
+    [array] $options Elements as follow:
+    -string template_name File name of the template to be used
+    -array  data          Context to pass through for template use
+    -array  options       Options to pass through for template use
+
+##### Return:
+    [string] The rendered template
+
+---
+
diff --git a/docs/Helpers/TerminusHelper.md b/docs/Helpers/TerminusHelper.md
new file mode 100644
index 000000000..31b3cc1dd
--- /dev/null
+++ b/docs/Helpers/TerminusHelper.md
@@ -0,0 +1,14 @@
+# Terminus\Helpers\TerminusHelper
+
+### __construct
+##### Description:
+    TerminusHelper constructor.
+
+##### Parameters:
+    [array] $options Options and dependencies for this helper
+
+##### Return:
+    [TerminusHelper] $this
+
+---
+
diff --git a/docs/Models/Collections/OrganizationUserMemberships.md b/docs/Models/Collections/OrganizationUserMemberships.md
index df1053e4e..abc754b01 100644
--- a/docs/Models/Collections/OrganizationUserMemberships.md
+++ b/docs/Models/Collections/OrganizationUserMemberships.md
@@ -5,13 +5,29 @@
     Adds a user to this organization
 
 ##### Parameters:
-    [User] $user User object of user to add to this organization
+    [string] $uuid UUID of user user to add to this organization
+    [string] $role Role to assign to the new member
 
 ##### Return:
     [Workflow] $workflow
 
 ---
 
+### get
+##### Description:
+    Retrieves models by either user ID, email address, or full name
+
+##### Parameters:
+    [string] $id Either a user ID, email address, or full name
+
+##### Return:
+    [OrganizationUserMembership]
+
+##### Throws:
+    TerminusException
+
+---
+
 ### fetch
 ##### Description:
     Fetches model data from API and instantiates its model instances
diff --git a/docs/Models/Environment.md b/docs/Models/Environment.md
index 424978cb2..807c52e62 100644
--- a/docs/Models/Environment.md
+++ b/docs/Models/Environment.md
@@ -68,6 +68,15 @@
 
 ---
 
+### countDeployableCommits
+##### Description:
+    Counts the number of deployable commits
+
+##### Return:
+    [int]
+
+---
+
 ### create
 ##### Description:
     Creates a new environment
@@ -241,6 +250,18 @@
 
 ---
 
+### setHttpsCertificate
+##### Description:
+    Add/Replace an HTTPS Certificate on the Environment
+
+##### Parameters:
+    [array] $options Certificate data`
+
+##### Return:
+    [$workflow]
+
+---
+
 ### unlock
 ##### Description:
     Disable HTTP Basic Access authentication on the web environment
diff --git a/docs/Models/Organization.md b/docs/Models/Organization.md
index 5c9838a4f..9da74f7c4 100644
--- a/docs/Models/Organization.md
+++ b/docs/Models/Organization.md
@@ -10,6 +10,18 @@
 
 ---
 
+### getFeature
+##### Description:
+    Returns a specific organization feature value
+
+##### Parameters:
+    [string] $feature Feature to check
+
+##### Return:
+    [mixed|null] Feature value, or null if not found
+
+---
+
 ### getSites
 ##### Description:
     Retrieves organization sites
diff --git a/docs/Models/OrganizationUserMembership.md b/docs/Models/OrganizationUserMembership.md
index 8cc72daf1..ec585e4a2 100644
--- a/docs/Models/OrganizationUserMembership.md
+++ b/docs/Models/OrganizationUserMembership.md
@@ -9,3 +9,15 @@
 
 ---
 
+### setRole
+##### Description:
+    Sets the user's role within this organization
+
+##### Parameters:
+    [string] $role Role for this user to take in the organization
+
+##### Return:
+    [Workflow]
+
+---
+
diff --git a/docs/Models/Site.md b/docs/Models/Site.md
index b53d28790..1df93473d 100644
--- a/docs/Models/Site.md
+++ b/docs/Models/Site.md
@@ -224,6 +224,15 @@
 
 ---
 
+### getTips
+##### Description:
+    Just the code branches
+
+##### Return:
+    [array]
+
+---
+
 ### getUpstreamUpdates
 ##### Description:
     Get upstream updates
@@ -354,15 +363,6 @@
 
 ---
 
-### tips
-##### Description:
-    Just the code branches
-
-##### Return:
-    [\stdClass]
-
----
-
 ### updateServiceLevel
 ##### Description:
     Update service level
diff --git a/utils/make-docs.php b/utils/make-docs.php
index 843a25df5..17d375563 100644
--- a/utils/make-docs.php
+++ b/utils/make-docs.php
@@ -1,11 +1,10 @@
 <?php
 
 define('TERMINUS_ROOT', dirname(__DIR__));
-require(TERMINUS_ROOT . '/php/utils.php');
+require(TERMINUS_ROOT . '/php/Terminus/Helpers/TerminusHelper.php');
+require(TERMINUS_ROOT . '/php/Terminus/Helpers/TemplateHelper.php');
 require(TERMINUS_ROOT . '/vendor/autoload.php');
 
-use Terminus\Utils;
-
 /**
  * Accepts an array representing a tokenized PHP file and sifts out all
  * sets of tokens meeting a specific pattern
@@ -116,13 +115,17 @@ function parseDocs($doc_string) {
  * @return bool    True if write was successful
  */
 function writeDocFile($namespace, $docs) {
+  $template_helper = new \Terminus\Helpers\TemplateHelper(['command' => null]);
+    
   $filename    = TERMINUS_ROOT . '/docs/'
     . str_replace(array('Terminus\\', '\\'), array('', '/'), $namespace)
     . '.md';
-  $rendered_doc = Utils\twigRender(
-    'doc.twig',
-    $docs,
-    array('namespace' => $namespace)
+  $rendered_doc = $template_helper->render(
+    [
+      'template_name' => 'doc.twig',
+      'data'          => $docs,
+      'options'       => ['namespace' => $namespace,],
+    ]
   );
   file_put_contents($filename, $rendered_doc);
   return true;
@@ -130,7 +133,8 @@ function writeDocFile($namespace, $docs) {
 
 $library_files   = array_merge(
   getFiles(TERMINUS_ROOT . '/php/Terminus/Models'),
-  getFiles(TERMINUS_ROOT . '/php/Terminus/Outputters')
+  getFiles(TERMINUS_ROOT . '/php/Terminus/Outputters'),
+  getFiles(TERMINUS_ROOT . '/php/Terminus/Helpers')
 );
 $tokenized_files = array();
 foreach ($library_files as $filename) {
@@ -141,9 +145,6 @@ function writeDocFile($namespace, $docs) {
   );
   $tokenized_files[$namespace] = getTokens($filename);
 }
-$tokenized_files['Terminus\\Auth'] = getTokens(TERMINUS_ROOT . '/php/Terminus/Auth.php');
-$tokenized_files['Terminus\\Helpers\\Input'] =
-  getTokens(TERMINUS_ROOT . '/php/Terminus/Helpers/Input.php');
 
 $file_functions = array();
 foreach ($tokenized_files as $namespace => $tokens) {