From 1d915bcb89d97777bcb9d4aafeea0e385388d9ff Mon Sep 17 00:00:00 2001 From: Richard Pappalardo Date: Tue, 3 May 2016 10:48:52 -0700 Subject: [PATCH] replace README.md with rst format (#70) Replace README.md with rst format and make some tweaks for PyPi --- .gitignore | 1 + README.md | 168 ------------------------------------------- README.rst | 204 +++++++++++++++++++++++++++++++++++++++++++++++++++++ setup.py | 7 +- 4 files changed, 208 insertions(+), 172 deletions(-) delete mode 100644 README.md create mode 100644 README.rst diff --git a/.gitignore b/.gitignore index 7963e8d..401317c 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,7 @@ venv *.pyc *.egg-info/ *.egg +dist/ .tox/ .DS_Store diff --git a/README.md b/README.md deleted file mode 100644 index f56da45..0000000 --- a/README.md +++ /dev/null @@ -1,168 +0,0 @@ -# ff-tool - -[![Build Status](https://travis-ci.org/rpappalax/ff-tool.svg?branch=master)](https://travis-ci.org/rpappalax/ff-tool) - -## Summary - -ff-tool is a Python CLI tool we've created to facilitate browser testing of -cloud services. It is largely a convenience wrapper we've written around -these amazing tools/libraries (see note below): - -- [mozdownload](https://github.com/mozilla/mozdownload) -- [mozprofile](https://github.com/mozilla/mozprofile) - -Our typical use case is launching various Firefox browser versions with a -fresh profile and loading custom preferences. This tool enables us to do this -quickly with a 1-liner from the CLI. - -## Features - -1. DownloadFirefox desktop versions (Nightly, Developer Edition, Beta, Release) -2. Manage profiles -3. Load test preferences - -## Notes - -If you plan on creating a tool of your own, please import the above lib -directly in your script(s). This tool was designed for convenience of our -team for testing Cloud Services and not intended to be used as a library. - -Profiles are stored in a temp directory by default which can be overridden. -Use caution if you specify your own profile directory as profile cleanup -functions can wipe out all profiles in your specified directory. - - -:bangbang: _**NOTE:** This tool is work in progress... USE AT YOUR OWN RISK_ :bangbang: - - -## Installation - -### Pre-requisites - -* Python >= 2.7 and virtualenv (Python 3 not yet supported) - -#### Windows Users - -* ff-tool will work on Windows, but requires quite a bit of setup. -* Also, installation behavior for the Firefox binary is different than for other OSes. In particular, ff-tool installs the Firefox binaries into a "\_temp" directory for all OSes (except Windows) to avoid clobbering your working browser. Unfortunately, the Windows installer -forces installation into C:\\Program Files. Since both the release and Beta versions of Firefox install into the same place, you also run the risk of installing one over another. -* Again, use at your own risk! - - -#### Windows: Installing Cygwin - * Download and install [Cygwin](https://cygwin.com/) - * A number of dependencies must also be installed including: - gcc, make, curl, pycrypto, python2, python-dev, etc. - 1. Right click on c:\cygwin64\cygwin.bat - 2. Run as administrator or you will suffer needlessly - - - - -### Build -```sh -$ make build -$ source ./venv/bin/activate -``` - -### Cleanup -```sh -$ deactivate -$ make clean -``` - -## Run -_When not specified, ff will use defaults_ - -## Help -```sh -$ ff -h -``` - -## Launch browser, clean profile - -* version: Nightly -* profile_name: \ -```sh -$ ff -``` - -* version: Developer Edition (aurora) -* profile_name: \ -```sh -$ ff -c aurora -``` - -## Launch browser, clean profile, specify profile name - -* version: Nightly -* profile_name: my_cool_profile1 - -**NOTE:** If the specified profile exists, we use it, if not we create a new one -with that name. - -```sh -$ ff -p my_cool_profile1 -``` - -# Custom Browser Prefs - -Firefox provides the ability for a user to change preferences in about:config. -For testing and automation this can be cumbersome as it usually involves many -small steps. - -As alternative, ff-tool provides a means for loading these prefs from a root -directory you specify via an environment variable. - -Example: -```sh -$ export PREFS_ROOT_DIR = '../services-test' -``` - -Custom prefs must be stored in the following directory/file structure: -// - -You must also include a prefs.ini file which specifies the environment(s) -in which each pref set is used. - -Example prefs.ini: -```sh -[DEFAULT] -pref_key = pref_value - -[dev] -pref_key = pref_value - -[stage] -pref_key = pref_value -``` - -# Cloud Services (only) - - -## Launch browser, clean profile, specify services-specific options... - -* version: Beta -* profile_name: my_cool_profile1 -* product: loop-server -* environment: stage -* test-type: e2e-test - -**NOTE:** If the specified profile exists, we use it, if not we create a new one -with that name. - -```sh -$ ff -c beta -p my_cool_profile1 -a loop-server -e stage -t e2e-test -``` - -## Download all browsers, but don't create a profile or launch any browsers... - -**NOTE:** This is useful for our daily refresh task where we make sure we have -the latest browsers installed. - -* version: all -* profile_name: none - -```sh -$ ff -c ALL --install-only -``` diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..4ff0be4 --- /dev/null +++ b/README.rst @@ -0,0 +1,204 @@ +======= +ff-tool +======= + +|Build Status| + +.. |Build Status| image:: https://travis-ci.org/rpappalax/ff-tool.svg?branch=dev + :target: https://travis-ci.org/rpappalax/ff-tool + +.. contents:: + +Summary +======= + +ff-tool is a Python CLI tool we’ve created to facilitate browser testing +of cloud services. It is largely a convenience wrapper we’ve written +around these amazing tools/libraries (see note below): + +- `mozdownload `_ +- `mozprofile `_ + +Our typical use case is launching various Firefox browser versions with +a fresh profile and loading custom preferences. This tool enables us to +do this quickly with a 1-liner from the CLI. + +Features +======== + +1. DownloadFirefox desktop versions (Nightly, Developer Edition, Beta, + Release) +2. Manage profiles +3. Load test preferences + +Notes +===== + +If you plan on creating a tool of your own, please import the above lib +directly in your script(s). This tool was designed for convenience of +our team for testing Cloud Services and not intended to be used as a +library. + +Profiles are stored in a temp directory by default which can be +overridden. Use caution if you specify your own profile directory as +profile cleanup functions can wipe out all profiles in your specified +directory. + +**NOTE:** + +This tool is work in progress… USE AT YOUR OWN RISK! + +Installation +============ + +**Pre-requisites** + +- Python >= 2.7 and virtualenv (Python 3 not yet supported) + +**Windows Users** + +- ff-tool will work on Windows, but requires quite a bit of setup. +- Also, installation behavior for the Firefox binary is different than + for other OSes. In particular, ff-tool installs the Firefox binaries + into a “\_temp” directory for all OSes (except Windows) to avoid + clobbering your working browser. Unfortunately, the Windows installer + forces installation into C:\\Program Files. Since both the release + and Beta versions of Firefox install into the same place, you also + run the risk of installing one over another. +- Again, use at your own risk! + +**Windows: Installing Cygwin** + +- Download and install: `Cygwin `_ +- Right click on: c:\\cygwin64\\cygwin.bat +- Run as administrator or you will suffer. +- A number of dependencies must also be installed including: gcc, make, + curl, pycrypto, python2, python-dev, etc. + +**Build** + +:: + + $ make build + $ source ./venv/bin/activate + +**Cleanup** + +:: + + $ deactivate + $ make clean + +Run +=== + +*When not specified, ff will use defaults* + +Help +==== + +:: + + $ ff -h + +Launch browser, clean profile +============================= + +- version: Nightly +- profile\_name: + +:: + + $ ff + +- version: Developer Edition (aurora) +- profile\_name: + +:: + + $ ff -c aurora + +Launch browser, clean profile, specify profile name +=================================================== + +- version: Nightly +- profile\_name: my\_cool\_profile1 + +**NOTE:** If the specified profile exists, we use it, if not we create a +new one with that name. + +:: + + $ ff -p my_cool_profile1 + + +Custom Browser Prefs +==================== + +Firefox provides the ability for a user to change preferences in +about:config. For testing and automation this can be cumbersome as it +usually involves many small steps. + +As alternative, ff-tool provides a means for loading these prefs from a +root directory you specify via an environment variable. + +Example: + +:: + + $ export PREFS_ROOT_DIR = '../services-test' + +Custom prefs must be stored in the following directory/file structure: + +You must also include a prefs.ini file which specifies the +environment(s) in which each pref set is used. + +Example prefs.ini: + +:: + + [DEFAULT] + pref_key = pref_value + + [dev] + pref_key = pref_value + + [stage] + pref_key = pref_value + + +Cloud Services (only) +===================== + +Launch browser, clean profile, specify services-specific options... +------------------------------------------------------------------- + +- version: Beta +- profile\_name: my\_cool\_profile1 +- product: loop-server +- environment: stage +- test-type: e2e-test + +**NOTE:** If the specified profile exists, we use it, if not we create a +new one with that name. + +:: + + $ ff -c beta -p my_cool_profile1 -a loop-server -e stage -t e2e-test + +Download all browsers, but don't create a profile or launch any browsers... +--------------------------------------------------------------------------- + +**NOTE:** This is useful for our daily refresh task where we make sure +we have the latest browsers installed. + +- version: all +- profile\_name: none + +:: + + $ ff -c ALL --install-only + + + + diff --git a/setup.py b/setup.py index 12b289b..e129468 100644 --- a/setup.py +++ b/setup.py @@ -5,10 +5,9 @@ from fftool import __version__ from setuptools import setup, find_packages here = os.path.abspath(os.path.dirname(__file__)) -with io.open(os.path.join(here, 'README.md'), encoding='utf8') as f: + +with io.open(os.path.join(here, 'README.rst'), encoding='utf8') as f: README = f.read() -with io.open(os.path.join(here, 'CHANGELOG.md'), encoding='utf8') as f: - CHANGES = f.read() extra_options = { 'packages': find_packages(), @@ -18,7 +17,7 @@ extra_options = { setup(name='ff-tool', version=__version__, description='Firefox CLI test setup tool', - long_description=README + '\n\n' + CHANGES, + long_description=README, classifiers=['Topic :: Software Development :: Quality Assurance', 'Topic :: Software Development :: Testing', 'Programming Language :: Python',