Add user, installation and testing guide

.github/CONTRIBUTING.rst

@@ -18,7 +18,8 @@ In order to contribute, you'll need to:
   1. Fork the repository.
 
   2. Create a branch, push your changes there. Don't forget to
-     :ref:`include news files for the changelog <howto_add_change_notes>`.
+     :ref:`include news files for the changelog <Adding change
+     notes with your PRs>`.
 
   3. Send it to us as a PR.
 

.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/README.rst

@@ -1,5 +1,3 @@
-.. _howto_add_change_notes:
-
 ---------------------------------
 Adding change notes with your PRs
 ---------------------------------

docs/contributing/guidelines.rst

@@ -1,5 +1,10 @@
 .. include:: ../../.github/CONTRIBUTING.rst
 
+.. seealso::
+
+   :ref:`Testing Guide`
+       Running the tests suite locally
+
 -----------------
 Contributing docs
 -----------------

docs/contributing/testing_guide.rst

@@ -0,0 +1,30 @@
+*************
+Testing Guide
+*************
+
+Welcome to the |project| Testing Guide!
+
+
+Getting the source code
+=======================
+
+getting ansible-pylibssh source:
+
+.. code-block:: shell-session
+
+    $ git clone https://github.com/ansible/pylibssh.git
+    $ cd pylibssh
+    $ pip install tox
+    $ tox -e build-dists
+
+Running tests
+==============
+
+.. code-block:: shell-session
+
+    $ tox -e test-binary-dists
+
+.. seealso::
+
+   :ref:`Installation Guide`
+       Installation from source

docs/index.rst

@@ -16,6 +16,9 @@ Welcome to |project|'s documentation!
    :maxdepth: 2
    :caption: Contents:
 
+   installation_guide
+   user_guide
+
 .. toctree::
    :caption: What's new
 
@@ -24,9 +27,10 @@ Welcome to |project|'s documentation!
 .. toctree::
    :caption: Contributing
 
-   contributing/code_of_conduct.rst
-   contributing/guidelines.rst
-   contributing/security.rst
+   contributing/code_of_conduct
+   contributing/guidelines
+   contributing/security
+   contributing/testing_guide
 
 
 

docs/installation_guide.rst

@@ -0,0 +1,84 @@
+******************
+Installation Guide
+******************
+
+Welcome to the |project| Installation Guide!
+
+
+Installing |project|
+====================
+
+This page describes how to install |project| on different platforms.
+
+.. contents::
+  :local:
+
+Prerequisites
+--------------
+You need Python 2.7 or 3.5+
+
+pylibssh requires libssh to be installed in particular:
+
+- libssh version 0.9.0 and later.
+
+  To install libssh refer to its `Downloads page
+  <https://www.libssh.org/get-it/>`__.
+
+Installing |project| with ``pip``
+---------------------------------
+
+|project| can be installed with ``pip``, the Python package manager.  If ``pip`` isn't already available on your system of Python, run the following commands to install it::
+
+    $ curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
+    $ python get-pip.py --user
+
+Then install |project|:
+
+.. parsed-literal::
+
+    $ pip install --user |project|
+
+.. note::
+
+    Running ``pip`` with ``sudo`` will make global changes to the system. Since ``pip`` does not coordinate with system package managers, it could make changes to your system that leaves it in an inconsistent or non-functioning state. This is particularly true for macOS. Installing with ``--user`` is recommended unless you understand fully the implications of modifying global files on the system.
+
+.. note::
+
+    Older versions of ``pip`` default to http://pypi.python.org/simple, which no longer works.
+    Please make sure you have the latest version of ``pip`` before installing |project|.
+    If you have an older version of ``pip`` installed, you can upgrade by following `pip's upgrade instructions <https://pip.pypa.io/en/stable/installing/#upgrading-pip>`_ .
+
+
+Running |project| from source (devel)
+--------------------------------------------
+
+|project| can be installed from source::
+
+    $ git clone https://github.com/ansible/pylibssh.git
+    $ cd pylibssh
+    $ pip install tox
+    $ tox -e build-dists
+
+``manylinux``-compatible wheels::
+
+    $ git clone https://github.com/ansible/pylibssh.git
+    $ cd pylibssh
+    $ pip install tox
+    $ tox -e build-dists-manylinux  # with Docker
+
+    # or with Podman
+    $ DOCKER_EXECUTABLE=podman tox -e build-dists-manylinux
+
+    # to enable shell script debug mode use
+    $ tox -e build-dists-manylinux -- -e DEBUG=1
+
+|project| also uses the following Python modules that need to be installed:
+
+.. code-block:: bash
+
+    $ pip install --user -r ./requirements.txt
+
+.. seealso::
+
+   :ref:`Getting Started with |project|`
+       Examples of using |project|

docs/user_guide.rst

@@ -0,0 +1,92 @@
+******************************
+Getting Started with |project|
+******************************
+
+Now that you have read the :ref:`installation guide <Installation Guide>` and
+installed |project| on a your system.
+
+.. 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