Add shared configuration snippet.

Usage instructions are modified accordingly with the usage of shared
configuration snippets.

Close #1.

Fix documentation typo.

Author: damienflament

CHANGELOG.md

@@ -6,6 +6,9 @@ The format is based on [Keep a Changelog],
 and this project adheres to [Semantic Versioning].
 
 ## [Unreleased]
+### Added
+ - Travis CI shared configuration snippet intented to be sourced in user
+   configuration (`dev.yml`).
 
 ## [0.1.2] - 2020-01-13
 ### Fixed

README.md

@@ -12,7 +12,7 @@ Helps to install Python to Travis CI machines in Linux, macOS and Windows.
 _travis-python_ is just a Bash script providing a helper function:
 
 ```bash
-install_python $LOCATION $SPECIFIER
+install_python <location> <specifier>
 ```
 
 The specified Python version, if found, will be installed at the specified
@@ -35,89 +35,31 @@ Usage
 To be able to use _travis-python_, the Travis machine needs to be configured
 to be able to run in the three operating systems.
 
-First, use a `shell` environment as it is the only minimal environment available
-in the three OS:
+The easiest way to do it is to [import][travis-config-imports] the shared
+configuration snippet:
 
 ```yaml
-language: shell
+import: neimad/travis-python:dev.yml
 ```
 
-Then, specify the required operating systems:
+Read [the configuration documentation] to understand how it works.
 
-```yaml
-os:
-  - linux
-  - osx
-  - windows
-```
-
-Finally, load the _travis-python_ script during the `pre-install` phase:
+Then, specify the wanted Python version using the `PYTHON` environment
+variable:
 
 ```yaml
-pre-install:
-  - curl -o travis-python.bash -sSL https://git.io/JeaZo
-    && source travis-python.bash
-  - install_python $LOCATION $VERSION
-```
+import: neimad/travis-python:dev.yml
 
-### Jobs for multiple Python versions
-
-You can run jobs for multiple Python versions by using an environment variable
-within the job matrix:
-
-```yaml
 env:
-  - PYTHON="3.7"
-  - PYTHON="3.6"
-
-pre-install:
-  - install_python $LOCATION $PYTHON
+  - PYTHON=3.8
+  - PYTHON=3.7
+  - PYTHON=2
 ```
+By default, it will generate a build matrix using the three operating systems
+available on Travis CI (Linux, macOS and Windows).
 
-### Caching data
-
-To speed up your jobs, you can cache the Python environment:
-
-```yaml
-pre-install:
-  - install_python $HOME/Python $PYTHON
-
-cache:
-  directories:
-    - $HOME/Python
-```
-
-### Minimal recommended configuration
-
-```yaml
-language: shell
-
-os:
-  - linux
-  - osx
-  - windows
-
-osx_image: xcode11
-
-env:
-  - PYTHON="3.8"
-  - PYTHON="3.7"
-  - PYTHON="3.6"
-  - PYTHON="2"
-
-pre-install:
-  - curl -o travis-python.bash -sSL https://git.io/JeaZo
-    && source travis-python.bash
-  - install_python $HOME/Python $PYTHON
-
-install: ...
-
-script: ...
-
-cache:
-  directories:
-    - $HOME/Python
-```
+The Python distribution is installed during the `pre-install` phase and
+available using the `python` program name (whether it is Python 2 or 3).
 
 Behind the scene
 ----------------
@@ -168,14 +110,17 @@ License
 
 `travis-python` is licensed under the [GNU GPL 3 or later][license].
 
-[license]: https://github.com/neimad/travis-python/blob/master/LICENSE.md
-[the changelog]: CHANGELOG.md
-[ci]: https://travis-ci.org/neimad/travis-python
 [ci-badge]: https://img.shields.io/travis/neimad/travis-python?style=flat-square
 [release-badge]: https://img.shields.io/github/v/tag/neimad/travis-python?sort=semver&style=flat-square
-
 [license-badge]: https://img.shields.io/github/license/neimad/travis-python?style=flat-square
+
+[license]: LICENSE.md
+[the changelog]: CHANGELOG.md
+[the configuration documentation]: doc/Travis_Configuration.md
 [look at the existing tickets]: https://github.com/neimad/travis-python/issues
 [make a pull request]: https://github.com/neimad/travis-python/pulls
+[ci]: https://travis-ci.org/neimad/travis-python
+
 [travis-python-versions]: https://docs.travis-ci.com/user/languages/python/#specifying-python-versions
+[travis-config-imports]: https://docs.travis-ci.com/user/build-config-imports/
 [shellspec]: https://shellspec.info

dev.yml

@@ -0,0 +1,19 @@
+# Travis CI configuration snippet to use the latest development version of
+# travis-python.
+#
+# Just import it in your Travis CI configuration:
+#
+#  import: neimad/travis-python:dev.yml
+#
+
+language: shell
+
+os:
+  - linux
+  - osx
+  - windows
+
+before_install:
+  - wget https://raw.githubusercontent.com/neimad/travis-python/master/travis-python.bash
+  - source travis-python.bash
+  - install_python $HOME/python $PYTHON

doc/Travis_Configuration.md

@@ -0,0 +1,63 @@
+# Travis CI Configuration
+
+This document helps you understand how the Travis CI machine is configured to
+use `travis-python` when you import one of ours shared configuration snippets.
+
+It is usefull if you want to use a custom configuration without importing
+snippet.
+
+## CI Environment
+
+The `shell` environment is used because it is the only minimal environment
+available in the three OSes:
+
+```yaml
+language: shell
+```
+
+## Operating system
+
+As `travis-python` is intented to be used to test Python software on Linux,
+macOS and Windows; all three are specified:
+
+```yaml
+os:
+  - linux
+  - osx
+  - windows
+```
+
+## Script loading
+
+The `travis-python` script is loaded during the `pre-install` phase.
+
+It need to be sourced in order to modify environment variables (like `PATH`) in
+the current shell. But as macOS machines use Bash 3.2, sourcing from `stdin` is
+not supported:
+
+```yaml
+pre-install:
+    - source <(curl -sSL $url) # not supported on Bash 3.2
+```
+
+So, the script is downloaded using `wget` then sourced:
+
+```yaml
+pre-install:
+  - wget https://raw.githubusercontent.com/neimad/travis-python/master/travis-python.bash
+  - source travis-python.bash
+```
+
+## Python installation
+
+Finally, the Python distribution can be installed in the `$HOME/python`
+directory:
+
+```yaml
+pre-install:
+    - ...
+    - install_python $HOME/python $PYTHON
+```
+
+The Python distribution version to install is specified using the `PYTHON`
+environment variable.