Improve documentation, add quick_start

README.md

@@ -7,6 +7,8 @@
 [![Codacy Badge](https://api.codacy.com/project/badge/Grade/124d1f6ec45e45deaf924e740670087f)](https://www.codacy.com/manual/ezh/cloudselect?utm_source=github.com&utm_medium=referral&utm_content=ezh/cloudselect&utm_campaign=Badge_Grade)
 [![code style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://black.readthedocs.io/en/stable)
 
+You may find a documentation at the <a href="https://cloudselect.readthedocs.io/" target="_blank">Read The Docs</a>
+
 ## Purpose
 
 We have to jump between nodes quickly. There is a list of cloud accounts. Each account has multiple regions. Some nodes are publicity available, some of them not. Dozen of nodes sit behind bastion hosts. And few of them sit behind a group of jump points. And they all have different SSH keys.
@@ -26,14 +28,17 @@ CloudSelect retrieves node list from the cloud, passes that list to FZF, adds so
 [![demo](https://raw.githubusercontent.com/ezh/cloudselect/master/docs/demo/2019-12-11_23-04-56%20cloudselect%20demo.gif)](https://github.com/ezh/cloudselect/tree/master/docs/demo)
 
 The tool is:
-1. connecting to bastion host with public IP 54.171.154.230
-2. using locally stored key on bastion because the usage of ssh-agent is restricted by security team ?lol? and sshd settings are `AllowTcpForwarding no`, `GatewayPorts no`
-3. jumping to 4 EC2 web instances in development environment that located in private subnet 172.30.x.x
-4. running `sudo -i` at startup
-5. entering `sudo` password 12345678
+
+1.  connecting to bastion host with public IP 54.171.154.230
+2.  using locally stored key on bastion because the usage of ssh-agent is restricted by security team ?lol? and sshd settings are `AllowTcpForwarding no`, `GatewayPorts no`
+3.  jumping to 4 EC2 web instances in development environment that located in private subnet 172.30.x.x
+4.  running `sudo -i` at startup
+5.  entering `sudo` password 12345678
 
 *And after that, we have four ready to use interactive sessions in our terminal...*
 
+You may find a demo files in <a href="https://github.com/ezh/cloudselect/tree/master/docs/demo" target="_blank">docs/demo</a> directory.
+
 ## Basic usage
 
 -   Connect to a single known_hosts server

docs/index.md

@@ -1,5 +1,3 @@
-#### FZF Cloud Select
-
 ## Purpose
 
 We have to jump between nodes quickly. There is a list of cloud accounts. Each account has multiple regions. Some nodes are publicity available, some of them not. Dozen of nodes sit behind bastion hosts. And few of them sit behind a group of jump points. And they all have different SSH keys.
@@ -19,50 +17,35 @@ CloudSelect retrieves node list from the cloud, passes that list to FZF, adds so
 [![demo](https://raw.githubusercontent.com/ezh/cloudselect/master/docs/demo/2019-12-11_23-04-56%20cloudselect%20demo.gif)](https://github.com/ezh/cloudselect/tree/master/docs/demo)
 
 The tool is:
-1. connecting to bastion host with public IP 54.171.154.230
-2. using locally stored key on bastion because the usage of ssh-agent is restricted by security team ?lol? and sshd settings are `AllowTcpForwarding no`, `GatewayPorts no`
-3. jumping to 4 EC2 web instances in development environment that located in private subnet 172.30.x.x
-4. running `sudo -i` at startup
-5. entering `sudo` password 12345678
+
+1.  connecting to bastion host with public IP 54.171.154.230
+2.  using locally stored key on bastion because the usage of ssh-agent is restricted by security team ?lol? and sshd settings are `AllowTcpForwarding no`, `GatewayPorts no`
+3.  jumping to 4 EC2 web instances in development environment that located in private subnet 172.30.x.x
+4.  running `sudo -i` at startup
+5.  entering `sudo` password 12345678
 
 *And after that, we have four ready to use interactive sessions in our terminal...*
 
+You may find a demo files in <a href="https://github.com/ezh/cloudselect/tree/master/docs/demo" target="_blank">docs/demo</a> directory.
+
 ## Basic usage
 
 -   Connect to a single known_hosts server
 -   Connect to a single EC2 AWS instance
 
+P.S. To be exact, *connect* or *execute* command or whatever you like
+
 ## Advanced usage
 
 -   Connect to multiple known_hosts servers, run `sudo -i` command at startup and enter `sudo` password
 -   Connect to multiple EC2 AWS instances, run `sudo -i` command at startup and enter `sudo` password
 -   Connect to multiple EC2 AWS instances through a *bastion* host, run `sudo -i` command at startup and enter `sudo` password
 
+P.S. To be exact, *connect* or *execute* command or whatever you like
+
 ## Features
 
 :rocket: We may use jump hosts even if jump host hasn't been configured to allow remote port forwarding and we have the following settings in sshd_config:
 
         AllowTcpForwarding no
         GatewayPorts no
-
-## Installation
-
-CloudSelect is on PyPi! You can install CloudSelect with a simple pip command:
-
-        pip install cloudselect
-
-Add profile bash completion:
-
-         complete -C cloudselect_completer cloudselect
-
-You may copy suitable wrapper from `example` directory.
-
-# License
-
-[MIT][mit] © [Alexey Aksenov][author] et [al][contributors]
-
-[mit]: https://opensource.org/licenses/MIT
-
-[author]: https://github.com/ezh
-
-[contributors]: https://github.com/ezh/cloudselect/graphs/contributors

docs/quick_start.md

@@ -0,0 +1,41 @@
+## Requirements
+
+CloudSelect is a Python software. <br/>
+It is tested against [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/cloudselect)](https://pypi.org/project/cloudselect/)<br/>
+The latest version is [![PyPI version](https://img.shields.io/pypi/v/cloudselect.svg)](https://pypi.org/project/cloudselect/)
+
+## Installation
+
+`pip install cloudselect` to install cloudselect.<br/>
+`git clone git@github.com:ezh/cloudselect.git` to clone the git repository for scripts and examples.<br/>
+You may find shell scripts for cloud select and an example of configurations in the <a href="https://github.com/ezh/cloudselect/tree/master/example" target="_blank">example</a> directory.<br/>
+You may find a demo configuration that was used for animated gif in <a href="https://github.com/ezh/cloudselect/tree/master/docs/demo" target="_blank">docs/demo</a>. Swarm of servers for the demo was created with Terraform.
+
+## Usage
+
+Execute `cloudselect` to see the list of profiles. It should be empty. <br/>
+Do `cp example/known_hosts.cloud.json ~/.config/cloudselect/` to copy `known_hosts` profile to `.config` directory. <br/>
+Execute `cloudselect` one more time to see the list of profiles. It should contain `known_hosts` profile. <br/>
+Run `cloudselect known_hosts` to invoke FZF selector on your local hosts and get a JSON result. <br/>
+
+**Feel free to copy shell scripts in the example directory to your local `bin` folder.**
+
+P.S. You may find a list of profiles in the configuration directory. Typical user config directories are:
+
+```
+Mac OS X:               ~/Library/Preferences/cloudselect
+Unix:                   ~/.config/cloudselect     # or in $XDG_CONFIG_HOME, if defined
+Win XP (not roaming):   C:\Documents and Settings\<username>\Application Data\cloudselect
+Win XP (roaming):       C:\Documents and Settings\<username>\Local Settings\Application Data\cloudselect
+Win 7+  (not roaming):  C:\Users\<username>\AppData\Local\cloudselect
+Win 7+  (roaming):      C:\Users\<username>\AppData\Roaming\cloudselect
+```
+
+## Tips
+
+Edit configuration with `cloudselect -e`<br/>
+Edit profile with `cloudselect -e known_hosts`<br/>
+Use SSH with `sh example/cloudssh known_hosts`<br/>
+Open multiple SSH connections in a TMUX window with `sh example/cloudssh-tmux known_hosts`<br/>
+Add bash profile autocompletion `complete -C cloudselect_completer <executable>`<br/>
+   like `complete -C cloudselect_completer cloudselect` or `complete -C cloudselect_completer cloudssh`

docs/theme/main.html

@@ -0,0 +1,14 @@
+{% extends "base.html" %}
+
+{% block extrahead %}
+<style>
+.github-fork-ribbon:before {
+  background-color: #2980B9;
+}
+</style>
+{% endblock %}
+
+{%- block footer %}
+  {% include "footer.html" %}
+<a class="github-fork-ribbon right-bottom fixed" href="https://github.com/ezh/cloudselect" data-ribbon="Fork me on GitHub" title="Fork me on GitHub">Fork me on GitHub</a>
+{% endblock %}

mkdocs.yml

@@ -2,6 +2,7 @@ edit_uri: tree/master/docs
 extra_css:
   - https://assets.readthedocs.org/static/css/badge_only.css
   - https://assets.readthedocs.org/static/css/readthedocs-doc-embed.css
+  - https://cdnjs.cloudflare.com/ajax/libs/github-fork-ribbon-css/0.2.3/gh-fork-ribbon.min.css
 extra_javascript:
   - readthedocs-data.js
   - https://assets.readthedocs.org/static/core/js/readthedocs-doc-embed.js
@@ -38,16 +39,18 @@ site_description: FZF selector for cloud instances
 site_name: CloudSelect
 
 theme:
+  custom_dir: 'docs/theme/'
   name: readthedocs
   highlightjs: true
   hljs_languages:
     - json
     - python
 
 nav:
-  - Home: index.md
+  - Overview: index.md
+  - Quick start: quick_start.md
   - Reference:
-      - Home: Reference/index.md
+      - Overview: Reference/index.md
       - CloudSelect: Reference/cloudselect.md
       - Selector: Reference/selector.md
       - Discovery plugins: Reference/discovery.md