Issue #279: Move to deploying the wiki from the repo (#416)

docs/Contributing.md

@@ -0,0 +1,89 @@
+# Contributing
+Thank you for your interest in contributing to Bee. Please take note and follow
+the guidelines for contributing to this project.
+
+## Issues
+Creating issues and commenting on existing issues are the the first steps to
+contributing.
+
+### Bugs
+If reporting a bug, please ensure you provide complete details of the bug
+including:
+- Steps to reproduce
+- Expected results
+- Actual results
+- Relevant environment information could include, if it is applicable to the
+bug:
+  - Bee version (get by typing `bee version` or `bee status`)
+  - Backdrop CMS version (get from `bee status`)
+  - PHP version (get from `bee status`)
+  - MySQL or MariaDB version
+  - OS and version (Remember: Windows is not supported natively but Bee can be
+  used within WSL2 and other virtual machines).
+  - Version of executable (if applicable)
+
+When you report a bug, please watch out for and respond promptly to any follow
+up questions that I or other contributors may have in clarifying your bug
+report.
+
+### Enhancements
+You are welcome to request new commands or improvements to existing commands.
+Please provide clear details as to why you want the improvement or what the
+command would be used for.
+
+All contributors make contributions voluntarily so please be patient and don't
+expect instant results.
+
+If you see an existing enhancement request that you would like, then feel free
+to add your support to that request.
+
+### Questions
+If you are unsure of some part of how bee operates and you have checked the
+documentation in [the Wiki](https://github.com/backdrop-contrib/bee/wiki) feel
+free to ask a question in the issue queue.
+
+## Pull Requests
+Pull requests must only relate to issues. You can indicate which issue it fixes
+by starting the description of the pull request with:
+`Fixes #000` where '000' is the issue number you are addressing. This will link
+the pull request to the issue.
+
+### Coding standards
+All code is expected to adhere to both:
+- [Backdrop CMS Coding and Documentation Standards](https://docs.backdropcms.org/documentation/coding-and-documentation-standards), specifically:
+  - [PHP coding standards](https://docs.backdropcms.org/php-standards)
+  - [Code documentation standards](https://docs.backdropcms.org/doc-standards)
+- Existing conventions within Bee
+
+Exceptions can be made where there are good reasons. For example, in the `eval`
+command we have the following where we specifically ignore a check for a
+discouraged PHP function on the next line:
+
+```php
+    // phpcs:ignore Squiz.PHP.Eval -- integral part of the command
+    eval($arguments['code'] . ';');
+```
+
+### Tests
+There are automated tests which test both functionality and coding standards,
+though the coding standards test is not comprehensive. If tests fail, please
+attempt to fix if you can. If you're not sure why tests have failed, ask.
+
+If you are adding a new command or making changes to the way a command works, a
+new functional test or changes to existing functional tests, respectively, may 
+be required. It is ok to request help if you are unsure about this.
+
+### Feedback and revisions
+If you are given feedback in a review, please act on all of it; it is time
+consuming and frustrating to have to ask for the same changes multiple times.
+If you don't understand, please ask for clarification. If you don't agree,
+please explain why you don't agree.
+
+## Wiki
+The Wiki is open to all to improve. New commands will need a change to the wiki
+and changes to existing commands may require a change to the wiki.
+Please follow existing patterns within the wiki and if you are unsure about
+something, ask before making a change.
+
+If you feel the Wiki is missing something but you don't know what the answer
+is, feel free to ask a question in the issue queue.

docs/Converting-integrations-from-Drush.md

@@ -0,0 +1,3 @@
+If your module has Drush integration via a `MODULE.drush.inc` file, you can use that as a basis for creating a `MODULE.bee.inc` integration. See [Extending Bee](https://github.com/backdrop-contrib/bee/wiki/Extending-Bee) for some background. Not every Drush internal function has a Bee equivalent (though the maintainer is open to adding more functions if it's helpful), and the command definition might be slightly different too.
+
+One example is the [S3 File System module](https://github.com/backdrop-contrib/s3fs), which has integrations for both Drush and Bee.

docs/Extending-Bee.md

@@ -0,0 +1,230 @@
+# API Information
+Source: https://github.com/backdrop-contrib/bee/blob/1.x-1.x/API.md
+
+## `HOOK_bee_command()`
+This hook can be invoked to provide additional commands to Bee. It should reside
+in a `bee` command file (*HOOK.bee.inc*) which should be placed in a
+custom/contrib module, in the `.bee` folder in the user's HOME directory or in
+the `.bee` folder in the parent folder of the Backdrop root directory.
+
+Implementations of this hook should return an associative array of command
+descriptors, where the keys are unique command names and the values are
+associative arrays, containing:
+
+- **description**: The translated description of the command.
+- **callback**: The name of the function that runs the command. Should be of the
+  form `COMMAND_bee_callback`.
+- **group**: The name of the group the command belongs to (used when listing all
+  commands together). Group names should be lowercase with individual words
+  separated by an underscore. See `bee help` for a list of existing groups.
+- **arguments**: (optional) An array of required arguments for the command,
+  where the keys are argument names and the values are translated argument
+  descriptions.
+- **multiple_argument**: (optional) The argument name that accepts multiple
+  values. Note the singular form of this key - only a single argument can have
+  multiple values.
+- **optional_arguments**: (optional) Generally, arguments are required
+  parameters and options are optional ones, but on the rare occasion that
+  optional argument(s) are needed, an array of argument names can be specified
+  here.
+- **options**: (optional) An array of options for the command, where the keys
+  are option names (these will be prepended with '--' when displayed to the
+  user) and the values are associative arrays containing:
+  - **description**: The translated option description.
+  - **value**: (optional) A translated word describing the value a user needs to
+    provide for this option. This will be displayed to the user in uppercase
+    after the option name.
+  - **short**: (optional) A short code for an option that does not require a
+    value. These will be prepended with '-' when displayed to the user. Any
+    short options are converted to the full option before being passed to the
+    command callback so you only need to check for the full option in your
+    function.
+- **aliases**: (optional) An array of alternate command names.
+- **bootstrap**: (optional) The bootstrap level required to run this command.
+  See *includes/globals.inc* for possible values.
+- **examples**: (optional) An array of example use-cases for the command, where
+  the keys are command strings (including `bee`, options, arguments, etc.) and
+  the values are translated explanations of the command string.
+
+Example:
+
+```php
+function poetry_bee_command() {
+  return array(
+    'poem' => array(
+      'description' => bt('Displays a customised poem.'),
+      'callback' => 'poem_bee_callback',
+      'group' => 'poetry',
+      'arguments' => array(
+        'name' => bt('The name to use in the poem.'),
+      ),
+      'options' => array(
+        'roses' => array(
+          'description' => bt('Make roses a different colour.'),
+          'value' => bt('Colour'),
+        ),
+        'short' => array(
+          'description' => bt('Display a shorter poem.'),
+          'short' => 's',
+        ),
+      ),
+      'aliases' => array('p'),
+      'examples' => array(
+        'bee poem HAL' => bt('Display a poem about HAL.'),
+        'bee poem --roses=Yellow Sarah' => bt('Display a poem about Sarah with yellow roses.'),
+        'bee poem --short Bob' => bt('Display a short poem about Bob.'),
+      ),
+    ),
+  );
+}
+```
+
+## `COMMAND_bee_callback()`
+This function is called when the user runs the given command (see
+`HOOK_bee_command()`). It is highly recommended to adhere to the suggested
+`COMMAND_bee_callback()` format to avoid collisions with other Backdrop function
+names.
+
+This callback function will receive two parameters:
+
+- **$arguments**: An associative array where the keys are argument names and the
+  values are user-provided values for those arguments. In the case where an
+  argument is allowed multiple values, an array of user-provided values is
+  passed.
+- **$options**: An associative array where the keys are option names (*not*
+  aliases) and the values are user-provided values for those options.
+
+The function can optionally return an array of elements to render as output. An
+element is an associative array, containing:
+
+- **type**: A string that determines which render function to call for
+  formatting and displaying the element. It should be one of: 'text', 'table'.
+- **variables**: An array of variables to pass to the specific render function.
+  See the individual `bee_render_TYPE()` functions in *includes/render.inc* for
+  details about their individual parameters.
+- **newline**: (optional) A boolean that determines whether or not to add a
+  newline character (`\n`) to the end of the output. Defaults to TRUE.
+
+Example:
+
+```php
+function poem_bee_callback($arguments, $options) {
+  // Get variables.
+  $name = $arguments['name'];
+  $colour = !empty($options['roses']) ? strtolower($options['roses']) : 'red';
+  $short = isset($options['short']);
+
+  // Generate poem.
+  if (!$short) {
+    $poem = bt("Roses are !colour\nViolets are blue\nMy name is !name\nHow about you?\n", array(
+      '!colour' => $colour,
+      '!name' => $name,
+    ));
+  }
+  else {
+    $poem = bt("!name is my name and poetry's my game!\n", array(
+      '!name' => $name,
+    ));
+  }
+
+  // Return render array.
+  return array(
+    array(
+      'type' => 'text',
+      'variables' => array(
+        'value' => $poem,
+      ),
+      'newline' => TRUE,
+    ),
+  );
+}
+```
+
+## Helper functions
+There are a number of helper functions that can be called to assist in
+performing various tasks. Read the documentation for them in their respective
+files.
+
+- **`bee_message()`** (*includes/miscellaneous.inc*)  
+  Any time a message needs to be shown to the user at completion of the
+  operation, this function should be used. It collects all messages and then
+  displays them to the user at the conclusion of the operation. A message, as
+  opposed to regular text, has a type; being one of: status, success, warning,
+  error or log. Note that 'log' messages are only displayed to the user when
+  'debug' mode is enabled.
+
+- **`bee_instant_message()`** (*includes/render.inc*)  
+  If a message needs to be displayed to users as the code happens, this
+  function should be used. This could be to output a message to say something
+  is going to happen before it happens, for example, downloading a file or
+  completing a database operation. It can also be used for more advanced
+  debugging as the message will output at the time of code execution and
+  and therefore can output information before a fatal error. It includes an
+  additional message type of 'debug'.
+  In many ways, this function is similar to 'bee_message()' but there are some
+  key differences:
+    - This function will output the message and optional data at the point in
+      the code when it happens rather than at the end.
+    - It includes the ability to output an array of data after the message for
+      'debug' messages.
+    - It includes the calling function and line number for 'debug' messages.
+
+- **`bt()`** (*includes/miscellaneous.inc*)  
+  All text that can be translated into other languages should be run through
+  this function. This is the Bee equivalent of Backdrop's `t()` function.
+
+- **`bee_get_temp()`** (*includes/filesystem.inc*)  
+  If a temporary directory is needed (e.g. for downloading files, etc. before
+  moving them to a more permanent location), this function will provide the path
+  to the temporary directory.
+
+- **`bee_delete()`** (*includes/filesystem.inc*)  
+  This helper function will delete a file or directory from the filesystem. If a
+  directory is specified, everything in that directory will be deleted in
+  addition to the directory itself.
+
+- **`bee_copy()`** (*includes/filesystem.inc*)  
+  This helper function will copy a file or directory from one location to
+  another. If a directory is specified as the source to be copied, everything in
+  that directory will be copied as well.
+
+- **`bee_render_text()`** (*includes/render.inc*)  
+  If regular text (i.e. not a message) needs to be shown to the user, this
+  function will allow it to be formatted and displayed. Note that any text
+  displayed by calling this function directly will be shown before any messages,
+  and before the final command output. As such, it is preferable to display text
+  to the user using the regular command output instead (where appropriate).
+
+- **`bee_format_text()`** (*includes/render.inc*)  
+  This helper function assists in formatting text; such as using different
+  colours and making the text bold. It can be used to format text that will be
+  displayed later (for example, in the command output).
+
+- **`bee_render_table()`** (*includes/render.inc*)  
+  If a table of information (e.g. columns or tabular data) needs to be shown to
+  the user, this function will allow it to be formatted and displayed. Note that
+  any information displayed by calling this function directly will be shown
+  before any messages, and before the final command output. As such, it is
+  preferable to display information to the user using the regular command output
+  instead (where appropriate).
+
+- **`bee_confirm()`** (*includes/input.inc*)  
+  This helper function will prompt the user to answer a yes/no question. This is
+  useful, for example, when a command needs confirmation before performing
+  certain, irreversible actions. If 'yes' mode is enabled, the affirmative
+  option will be automatically chosen for the user.
+
+- **`bee_choice()`** (*includes/input.inc*)  
+  This helper function will prompt the user to select an option from a list of
+  choices. Since the selection of an appropriate answer cannot be automated
+  during the execution of the command, it is recommended that commands provide
+  an option that the user can specify when running the command initially.
+
+- **`bee_input()`** (*includes/input.inc*)  
+  This helper function will prompt the user to enter a string of data. This is
+  useful, for example, when the command needs information from the user that
+  cannot be expressed as a yes/no question, or as a selection from a finite list
+  of choices - e.g. the user's name or email address. Since the collection of
+  this information cannot be automated during the execution of the command, it
+  is recommended that commands provide an option that the user can specify when
+  running the command initially.

docs/Home.md

@@ -0,0 +1,11 @@
+<img src="https://raw.githubusercontent.com/backdrop-contrib/bee/1.x-1.x/images/bee.png" align="right" width="150" height="157">
+
+Bee is a command line utility for Backdrop CMS. It includes commands that allow developers to interact with Backdrop sites, performing actions like:
+
+- Running cron
+- Clearing caches
+- Downloading and installing Backdrop
+- Downloading, enabling and disabling projects
+- Viewing information about a site and/or available projects
+
+This wiki will provide information more detailed or lengthy than what's included in the [README](https://github.com/backdrop-contrib/bee/blob/1.x-1.x/README.md) file.

docs/Installation-on-shared-hosting.md

@@ -0,0 +1,48 @@
+## Introduction
+
+It may be possible to use Bee on your shared hosting if you have SSH access (or a virtual terminal - see Advanced > Terminal in your cPanel or equivalent) and if it will support aliases. See [this META issue](https://github.com/backdrop-contrib/bee/issues/154) for a list of shared hosts where this method has been tested and confirmed to work using the simple test above.
+
+## Manual (based on cPanel File Manager)
+- Download zip from GitHub
+  - Click on green 'Code' button
+  - Click on 'Download ZIP'
+- Upload zip to root of your home folder on your shared hosting account
+- Extract zip to root of home folder
+  - Select the uploaded zip file
+  - Click on 'Extract'
+  - Leave the path blank
+  - Click on 'Extract File(s)'
+- Rename folder to 'bee'
+- Add alias
+  - Open .bashrc to Edit
+  - Add `alias bee='~/bee/bee.php'` to the bottom of the file
+  - Click 'Save Changes'
+
+You should now be able to complete the test by accessing your backdrop folder through SSH or your virtual terminal.
+
+## Using Git
+
+- On your cPanel homepage, click on 'Git™ Version Control' under Files (if this isn't there in your cPanel, you won't be able to use this method and will need to use the manual method above)
+- Click Create
+- Ensure the switch for 'Clone a Repository' is switched on
+- Copy the Clone URL from this Git repository (Code>Clone) and paste it into the 'Clone URL' field
+- enter the folder name (i.e. 'bee') under 'Repository Path'
+- enter a 'Repository Name; (e.g 'Bee' or 'Backdrop Bee' )
+- Click 'Create'
+- Add alias
+  - Open .bashrc to Edit
+  - Add `alias bee='~/bee/bee.php'` to the bottom of the file
+  - Click 'Save Changes'
+
+You should now be able to complete the test by accessing your backdrop folder through SSH or your virtual terminal.
+
+### Updates
+You will be able to update your installation by clicking on 'Manage' and then 'Update'.
+
+## Troubleshooting
+### Bee doesn't work after adding the alias
+After adding the alias to .bashrc, Bee didn't work at all. 
+#### Solution
+Either:
+1. Log out of your SSH session, and log back in
+2. Re-load the bash configuration using the command `source .bashrc`