diff --git a/docs/changelog-fragments/145.doc.rst b/docs/changelog-fragments/145.doc.rst new file mode 100644 index 000000000..10be7fbf4 --- /dev/null +++ b/docs/changelog-fragments/145.doc.rst @@ -0,0 +1,2 @@ +Added the initial installation guide to docs +-- by :user:`ganeshrn` and :user:`webknjaz` diff --git a/docs/conf.py b/docs/conf.py index 22a6308c0..6d28a7b18 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -149,6 +149,7 @@ # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = { 'cython': ('https://cython.readthedocs.io/en/latest', None), + 'packaging': ('https://packaging.python.org', None), 'pip': ('https://pip.pypa.io/en/latest', None), 'python': ('https://docs.python.org/3', None), 'python2': ('https://docs.python.org/2', None), diff --git a/docs/contributing/testing_guide.rst b/docs/contributing/testing_guide.rst index 59977dc2e..44d487909 100644 --- a/docs/contributing/testing_guide.rst +++ b/docs/contributing/testing_guide.rst @@ -61,6 +61,11 @@ your machine. .. _tox v3.8.0: https://tox.readthedocs.io/en/latest/changelog.html#v3-8-0-2019-03-27 +.. seealso:: + + :ref:`Installing |project|` + Installation from source + Getting the source code ======================= @@ -124,7 +129,7 @@ Additionally, there's a separate workflow that runs linting\ [dir:pylibssh] $ python -m tox -e lint # pre-commit.com tool Continuous delivery -^^^^^^^^^^^^^^^^^^^ +=================== Besides testing and linting, |project| also has `GitHub Actions workflows CI/CD`_ set up to publish those same diff --git a/docs/index.rst b/docs/index.rst index f6cfe6662..6a132fc1e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,6 +16,7 @@ Welcome to |project|'s documentation! :maxdepth: 2 :caption: Contents: + installation_guide user_guide .. toctree:: diff --git a/docs/installation_guide.rst b/docs/installation_guide.rst new file mode 100644 index 000000000..dc6a8b956 --- /dev/null +++ b/docs/installation_guide.rst @@ -0,0 +1,131 @@ +******************** +Installing |project| +******************** + +This page describes how to install |project| using +:std:doc:`pip:index`. Consult with :std:doc:`pip docs +` if you are not sure whether you have it +set up. + +.. contents:: + :local: + +Pre-compiled binary distributions +================================= + +|project| contains :std:doc:`Cython `-based +:std:term:`CPython C-extension modules `. Unlike :std:term:`pure-Python modules +`, these must be pre-compiled +before consumption. + +We publish :std:ref:`platform-specific wheels ` to PyPI. They are built against different arch, +CPython and OS versions so in 99% of cases, you may +seamlessly install |project| not needing any external +dependencies on your system. + +It should be enough for you to just have Python 2.7 or +3.5+ and a recent :std:doc:`pip ` installed. + +.. attention:: + + Please make sure you have the latest version of + :std:doc:`pip ` before installing |project|. + + If you have a version of :std:doc:`pip ` + older than 8.1, it'll be unable to pick up OS-specific + Python package distributions from PyPI and will try to + fall back to building it from source which would require + more extra dependencies to succeed. + You can upgrade by following :std:ref:`pip's upgrade + instructions `. + +To install |project|, just run: + +.. parsed-literal:: + + $ pip install --user |project| + +.. tip:: + + Avoid running :std:doc:`pip ` with + :command:`sudo` as this will make global changes to the + system. Since :std:doc:`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 :std:ref:`\-\\\\-user + ` is recommended unless you + understand fully the implications of modifying global + files on the system. + +Installing |project| from source distribution (PyPI) +==================================================== + +Installing |project| from source is a bit more complicated. +First, pylibssh requires libssh to be compiled against, in +particular, version 0.9.0 or newer. Please refer to `libssh +Downloads page `__ for more +information about installing it. Make sure that you have the +development headers too. + +Another essential build dependency is GCC. You may already +have it installed but if not, consult with your OS docs. + +Once you have the build prerequisites, the following command +should download the tarball, build it and then install into +your current env: + +.. parsed-literal:: + + $ pip install \\ + --user \\ + --no-binary |project| \\ + |project| + +Building |project| dists from the ``devel`` branch in Git +========================================================= + +Since our build processes are tox_-centric, let's +install it first: + +.. code-block:: shell-session + + $ python -m pip install 'tox >= 3.19.0' --user + +.. _tox: https://tox.readthedocs.io + +Now, let's grab the source of |project|: + +.. code-block:: shell-session + + $ git clone https://github.com/ansible/pylibssh.git ~/src/github/ansible/pylibssh + $ # or, if you use SSH: + $ git clone git@github.com:ansible/pylibssh.git ~/src/github/ansible/pylibssh + $ cd ~/src/github/ansible/pylibssh + [dir:pylibssh] $ + +Finally, you can build the dists for the current env using: + +.. code-block:: shell-session + + [dir:pylibssh] $ tox -e build-dists + +If you want to generate the whole matrix of ``manylinux``-\ +compatible wheels, use: + +.. code-block:: shell-session + + [dir:pylibssh] $ tox -e build-dists-manylinux # with Docker + + [dir:pylibssh] $ # or with Podman + [dir:pylibssh] $ DOCKER_EXECUTABLE=podman tox -e build-dists-manylinux + +.. seealso:: + + :ref:`Getting Started with |project|` + Examples of getting started + + :ref:`Continuous delivery` + Using nightly builds to test your project against diff --git a/docs/user_guide.rst b/docs/user_guide.rst index 0e21515ea..ad884ce9d 100644 --- a/docs/user_guide.rst +++ b/docs/user_guide.rst @@ -2,6 +2,9 @@ Getting Started with |project| ****************************** +Now that you have read the :ref:`installation guide ` and +installed |project| on a your system. + .. contents:: :local: