Add user, installation and testing guide #112

ganeshrn · 2020-07-27T14:06:15Z

SUMMARY

Add user, installation and testing guide

ISSUE TYPE

Docs Pull Request

ADDITIONAL INFORMATION

webknjaz · 2020-07-27T14:51:00Z

docs/guide/user_guide/intro_getting_started.rst

+
+Copy file from remote host
+===========================
+.. code-block:: python


There should usually be some whitespace before code-blocks

Suggested change

.. code-block:: python

.. code-block:: python

webknjaz · 2020-07-27T14:53:05Z

docs/guide/user_guide/index.rst

+##########
+User Guide
+##########


It'd be nice to use the same style for titles across the project

Suggested change

##########

User Guide

##########

==========

User Guide

==========

webknjaz · 2020-07-27T14:54:07Z

docs/guide/testing_guide/unit_testing.rst

+Running tests
+==============
+
+.. code-block:: shell-session
+    $ tox -e test-binary-dists


This should mention that it expects the test targets to be pre-built in ./dist/

webknjaz

Also, the URL nesting is too deep. This project is not as complex as Ansible Engine and doesn't need that. Besides, it's weird to have to navigate this deep in almost empty docs. Let's have just flat files without dirs or nested indexes and, if needed in the future, we'd move things around.

webknjaz · 2020-07-27T14:54:50Z

docs/guide/testing_guide/unit_testing.rst

@@ -0,0 +1,25 @@
+.. _testing_guide:
+.. _unit_testing_guide:


this shouldn't be "unit-testing" it's just testing.

webknjaz · 2020-07-27T14:56:02Z

docs/guide/installation_guide/intro_installation.rst

+
+ansible-pylibssh also uses the following Python modules that need to be installed [1]_:
+
+.. code-block:: bash


Suggested change

.. code-block:: bash

.. code-block:: shell-session

webknjaz · 2020-07-27T14:56:27Z

docs/guide/installation_guide/intro_installation.rst

+ansible-pylibssh 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


This should probably just include a part of README instead of a copy

webknjaz · 2020-07-27T14:57:23Z

docs/guide/installation_guide/intro_installation.rst

+
+Prerequisites
+--------------
+You need Python 2.7 or 3.5+


There should be some whitespace after RST titles

Suggested change

You need Python 2.7 or 3.5+

You need Python 2.7 or 3.5+

webknjaz · 2020-07-27T14:58:34Z

README.rst

@@ -63,35 +63,6 @@ pylibssh requires libssh to be installed in particular:
  <https://www.libssh.org/get-it/>`__.


-Building the module


Instead of removing, use comment markers like .. DO-NOT-REMOVE-SOME-UNIQUE-NAME in order to single-source parts of README into the docs.

webknjaz · 2020-07-27T15:04:07Z

docs/guide/user_guide/intro_getting_started.rst

+.. code-block:: python
+
+  chan = ssh.new_channel()
+  print("stdout:\n%s\n stderr:\n%s\n returncode:\n%s\n" % (resp.stdout, resp.stderr, resp.returncode))


It's not clear what resp is here.

webknjaz · 2020-07-27T15:06:06Z

docs/guide/user_guide/intro_getting_started.rst

+.. code-block:: python
+
+   from pylibsshext._libssh_version import LIBSSH_VERSION
+
+   print(LIBSSH_VERSION)


Instead of putting Python sources in RST, let's put them in Python files and just include their contents (full or partial). It's easier to maintain files with complete sources that are just included in guides in parts. And it's possible to lint/check those files too, unlike code blocks in sphinx.

(you may delegate this to me if you want as I have a lot of experience using the inclusions)

webknjaz · 2020-07-27T15:07:12Z

docs/guide/user_guide/intro_getting_started.rst

+.. _intro_getting_started:
+
+***************
+Getting Started


I think this should specify that this is low-level/paramiko-like API

webknjaz · 2020-07-27T15:08:42Z

docs/guide/user_guide/intro_getting_started.rst

+Getting Started
+***************
+
+Now that you have read the :ref:`installation guide<installation_guide>` and installed ansible-pylibssh on a your system.


It's better to maintain spaces for readability + typo

Suggested change

Now that you have read the :ref:`installation guide<installation_guide>` and installed ansible-pylibssh on a your system.

Now that you have read the :ref:`installation guide <installation_guide>` and installed |project| on your system.

Alternatively, this would work too

Suggested change

Now that you have read the :ref:`installation guide<installation_guide>` and installed ansible-pylibssh on a your system.

Now that you have read the :ref:`installation_guide` and installed |project| on your system.

webknjaz · 2020-07-27T15:10:00Z

docs/guide/user_guide/intro_getting_started.rst

+Creating a SSH session
+======================


Suggested change

Creating a SSH session

======================

Creating an SSH session

=======================

webknjaz · 2020-08-04T14:11:16Z

docs/installation_guide.rst

+|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


This is a very bad idea to advertise. Link to the PyPA packaging docs instead.

TODO: get rid of it.

webknjaz · 2020-08-04T14:12:19Z

docs/installation_guide.rst

+
+.. note::
+
+    Older versions of ``pip`` default to http://pypi.python.org/simple, which no longer works.


This is not really true, there's a redirect.

TODO: Stop vendoring a copy of the PyPA guides, link there instead.

docs/_samples/get_version.py

webknjaz · 2020-09-01T21:54:08Z

I've split this into #141, #142 and #145.

webknjaz reviewed Jul 27, 2020

View reviewed changes

webknjaz requested changes Jul 27, 2020

View reviewed changes

webknjaz added the documentation Improvements or additions to documentation label Jul 27, 2020

webknjaz self-assigned this Jul 28, 2020

webknjaz marked this pull request as draft July 28, 2020 15:52

webknjaz force-pushed the docs branch 2 times, most recently from 0a6e9e4 to a5b711b Compare August 3, 2020 16:04

webknjaz reviewed Aug 4, 2020

View reviewed changes

webknjaz force-pushed the docs branch 3 times, most recently from 2962586 to 8c38119 Compare August 7, 2020 18:25

ganeshrn commented Aug 9, 2020

View reviewed changes

docs/_samples/get_version.py Show resolved Hide resolved

webknjaz force-pushed the docs branch from 0829cf6 to 964bf56 Compare August 11, 2020 23:25

ganeshrn and others added 13 commits August 12, 2020 20:35

Add user, installation and testing guide

ea7deec

Restore the original README

a672119

Fix RST and Sphinx syntax

3ecabde

Use |project| substitution in guides

c8744c3

Extract install guide into the top level

a54344a

Extract user guide to the top level

9e7182e

Pull the testing guide into the top level

d3660cf

Drop unnecessary "User Guide" title

e3b78fd

🚚 Migrate user guide snippets to files

9eb4a55

Relocate testing guide under contributing

5009237

Interlink the testing guide from contributing page

b0ab7e3

Drop manually maintained RST ref labels

2c8d329

Drop unnecessary RST file endings from index ToC

c7921dd

webknjaz force-pushed the docs branch from 964bf56 to c7921dd Compare August 12, 2020 18:35

webknjaz closed this Sep 1, 2020

webknjaz linked an issue Sep 1, 2020 that may be closed by this pull request

[TODO] Document how development and testing works #70

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add user, installation and testing guide #112

Add user, installation and testing guide #112

ganeshrn commented Jul 27, 2020

webknjaz Jul 27, 2020

webknjaz Jul 27, 2020

webknjaz Jul 27, 2020

webknjaz left a comment

webknjaz Jul 27, 2020

webknjaz Jul 27, 2020

webknjaz Jul 27, 2020

webknjaz Jul 27, 2020

webknjaz Jul 27, 2020

webknjaz Jul 27, 2020

webknjaz Jul 27, 2020

webknjaz Jul 27, 2020

webknjaz Jul 27, 2020

webknjaz Jul 27, 2020

webknjaz Jul 27, 2020

webknjaz Jul 27, 2020

webknjaz Aug 4, 2020

webknjaz Aug 4, 2020

webknjaz commented Sep 1, 2020


		ansible-pylibssh also uses the following Python modules that need to be installed [1]_:

		.. code-block:: bash

		@@ -63,35 +63,6 @@ pylibssh requires libssh to be installed in particular:
		<https://www.libssh.org/get-it/>`__.


		Building the module

	Now that you have read the :ref:`installation guide<installation_guide>` and installed ansible-pylibssh on a your system.
	Now that you have read the :ref:`installation guide <installation_guide>` and installed \|project\| on your system.


		.. note::

		Older versions of ``pip`` default to http://pypi.python.org/simple, which no longer works.

Add user, installation and testing guide #112

Add user, installation and testing guide #112

Conversation

ganeshrn commented Jul 27, 2020

SUMMARY

ISSUE TYPE

ADDITIONAL INFORMATION

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

webknjaz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

webknjaz commented Sep 1, 2020