Add initial user guide doc

.pre-commit-config.yaml

@@ -50,7 +50,11 @@ repos:
 
   # Heavy checks:
   - id: check-ast
+    exclude: >-
+      ^docs/_samples/.*\.py$
   - id: debug-statements
+    exclude: >-
+      ^docs/_samples/.*\.py$
 
 - repo: https://gitlab.com/pycqa/flake8.git
   rev: 3.8.2
@@ -65,6 +69,8 @@ repos:
     - wemake-python-styleguide
     files: >-
       ^.*\.p(xd|y|yx)$
+    exclude: >-
+      ^docs/_samples/.*\.py$
     types: [file]
 
 - repo: git://github.com/Lucas-C/pre-commit-hooks-markup
@@ -78,6 +84,8 @@ repos:
   rev: 5.0.2
   hooks:
   - id: pydocstyle
+    exclude: >-
+      ^docs/_samples/.*\.py$
 
 # - repo: local
 #   hooks:

docs/_samples/copy_files.py

@@ -0,0 +1,50 @@
+from pylibsshext.errors import LibsshSessionException
+from pylibsshext.session import Session
+
+
+ssh = Session()
+
+HOST = 'CHANGEME'
+USER = 'CHANGEME'
+PASSWORD = 'CHANGEME'
+TIMEOUT = 30
+PORT = 22
+try:
+    ssh.connect(
+        host=HOST,
+        user=USER,
+        password=PASSWORD,
+        timeout=TIMEOUT,
+        port=PORT,
+    )
+except LibsshSessionException as ssh_exc:
+    print(f'Failed to connect to {HOST}:{PORT} over SSH: {ssh_exc!s}')
+
+print(f'{ssh.is_connected=}')
+
+ssh_channel = ssh.new_channel()
+cmd_resp = ssh_channel.write(b'ls')
+print(f'stdout:\n{cmd_resp.stdout}\n')
+print(f'stderr:\n{cmd_resp.stderr}\n')
+print(f'return code: {cmd_resp.returncode}\n')
+ssh_channel.close()
+
+chan_shell = ssh.invoke_shell()
+chan_shell.sendall(b'ls')
+data = chan_shell.read_bulk_response(timeout=2, retry=10)
+chan_shell.close()
+print(data)
+
+remote_file = '/etc/hosts'
+local_file = '/tmp/hosts'
+sftp = SFTP(ssh)
+sftp.get(remote_file, local_file)
+sftp.close()
+
+remote_file = '/etc/hosts'
+local_file = '/tmp/hosts'
+sftp = SFTP(ssh)
+sftp.put(remote_file, local_file)
+sftp.close()
+
+ssh.close()

docs/_samples/get_version.py

@@ -0,0 +1,14 @@
+from pylibsshext import (
+    __full_version__,  # string with both ansible-pylibssh and libssh versions
+)
+from pylibsshext import (
+    __libssh_version__,  # linked libssh lib version as a string
+)
+from pylibsshext import __version__  # ansible-pylibssh version as a string
+from pylibsshext import __version_info__  # ansible-pylibssh version as a tuple
+
+
+print(f'{__full_version__=}')
+print(f'{__libssh_version__=}')
+print(f'{__version__=}')
+print(f'{__version_info__=}')

docs/changelog-fragments/141.doc.rst

@@ -0,0 +1,2 @@
+Added the initial user guide to docs
+-- by :user:`ganeshrn` and :user:`webknjaz`

docs/index.rst

@@ -16,6 +16,8 @@ Welcome to |project|'s documentation!
    :maxdepth: 2
    :caption: Contents:
 
+   user_guide
+
 .. toctree::
    :caption: What's new
 

docs/user_guide.rst

@@ -0,0 +1,89 @@
+******************************
+Getting Started with |project|
+******************************
+
+.. contents::
+   :local:
+
+
+.. tip::
+
+   The examples on this page use Python 3.8. If your interpreter
+   is older, you may need to modify the syntax when copying the
+   snippets.
+
+
+Checking software versions
+==========================
+
+.. literalinclude:: _samples/get_version.py
+   :language: python
+
+
+Creating a SSH session
+======================
+
+.. attention::
+
+   The APIs that are shown below, are low-level. You should
+   take a great care to ensure you process any exceptions that
+   arise and always close all the resources once they are no
+   longer necessary.
+
+.. literalinclude:: _samples/copy_files.py
+   :language: python
+   :lines: -5
+   :emphasize-lines: 5
+
+
+Connecting with remote SSH server
+=================================
+
+.. literalinclude:: _samples/copy_files.py
+   :language: python
+   :lines: 7-23
+   :emphasize-lines: 7-13
+
+
+Passing a command and reading response
+======================================
+
+.. literalinclude:: _samples/copy_files.py
+   :language: python
+   :lines: 25-30
+   :emphasize-lines: 2
+
+
+Opening a remote shell passing command and receiving response
+=============================================================
+
+.. literalinclude:: _samples/copy_files.py
+   :language: python
+   :lines: 32-36
+   :emphasize-lines: 2-3
+
+
+Fetch file from remote host
+===========================
+
+.. literalinclude:: _samples/copy_files.py
+   :language: python
+   :lines: 38-42
+   :emphasize-lines: 3-4
+
+
+Copy file to remote host
+========================
+
+.. literalinclude:: _samples/copy_files.py
+   :language: python
+   :lines: 44-48
+   :emphasize-lines: 3-4
+
+
+Closing SSH session
+===================
+
+.. literalinclude:: _samples/copy_files.py
+   :language: python
+   :lines: 50