1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/testing/mozbase/docs/mozprofile.rst Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,99 @@
1.4 +:mod:`mozprofile` --- Create and modify Mozilla application profiles
1.5 +====================================================================
1.6 +
1.7 +Mozprofile_ is a python tool for creating and managing profiles for Mozilla's
1.8 +applications (Firefox, Thunderbird, etc.). In addition to creating profiles,
1.9 +mozprofile can install addons_ and set preferences_ Mozprofile can be utilized
1.10 +from the command line or as an API.
1.11 +
1.12 +The preferred way of setting up profile data (addons, permissions, preferences
1.13 +etc) is by passing them to the profile_ constructor.
1.14 +
1.15 +Addons
1.16 +------
1.17 +
1.18 +.. automodule:: mozprofile.addons
1.19 + :members:
1.20 +
1.21 +Addons may be installed individually or from a manifest.
1.22 +
1.23 +Example::
1.24 +
1.25 + from mozprofile import FirefoxProfile
1.26 +
1.27 + # create new profile to pass to mozmill/mozrunner
1.28 + profile = FirefoxProfile(addons=["adblock.xpi"])
1.29 +
1.30 +Command Line Interface
1.31 +----------------------
1.32 +
1.33 +.. automodule:: mozprofile.cli
1.34 + :members:
1.35 +
1.36 +The profile to be operated on may be specified with the ``--profile``
1.37 +switch. If a profile is not specified, one will be created in a
1.38 +temporary directory which will be echoed to the terminal::
1.39 +
1.40 + (mozmill)> mozprofile
1.41 + /tmp/tmp4q1iEU.mozrunner
1.42 + (mozmill)> ls /tmp/tmp4q1iEU.mozrunner
1.43 + user.js
1.44 +
1.45 +To run mozprofile from the command line enter:
1.46 +``mozprofile --help`` for a list of options.
1.47 +
1.48 +Permissions
1.49 +-----------
1.50 +
1.51 +.. automodule:: mozprofile.permissions
1.52 + :members:
1.53 +
1.54 +You can set permissions by creating a ``ServerLocations`` object that you pass
1.55 +to the ``Profile`` constructor. Hosts can be added to it with
1.56 +``add_host(host, port)``. ``port`` can be 0.
1.57 +
1.58 +Preferences
1.59 +-----------
1.60 +
1.61 +.. automodule:: mozprofile.prefs
1.62 + :members:
1.63 +
1.64 +Preferences can be set in several ways:
1.65 +
1.66 +- using the API: You can make a dictionary with the preferences and pass it to
1.67 + the ``Profile`` constructor. You can also add more preferences with the
1.68 + ``Profile.set_preferences`` method.
1.69 +- using a JSON blob file: ``mozprofile --preferences myprefs.json``
1.70 +- using a ``.ini`` file: ``mozprofile --preferences myprefs.ini``
1.71 +- via the command line: ``mozprofile --pref key:value --pref key:value [...]``
1.72 +
1.73 +When setting preferences from an ``.ini`` file or the ``--pref`` switch,
1.74 +the value will be interpolated as an integer or a boolean
1.75 +(``true``/``false``) if possible.
1.76 +
1.77 +Profile
1.78 +--------------------
1.79 +
1.80 +.. automodule:: mozprofile.profile
1.81 + :members:
1.82 +
1.83 +Resources
1.84 +-----------
1.85 +Other Mozilla programs offer additional and overlapping functionality
1.86 +for profiles. There is also substantive documentation on profiles and
1.87 +their management.
1.88 +
1.89 +- ProfileManager_: XULRunner application for managing profiles. Has a GUI and CLI.
1.90 +- python-profilemanager_: python CLI interface similar to ProfileManager
1.91 +- profile documentation_
1.92 +
1.93 +
1.94 +.. _Mozprofile: https://github.com/mozilla/mozbase/tree/master/mozprofile
1.95 +.. _addons: https://developer.mozilla.org/en/addons
1.96 +.. _preferences: https://developer.mozilla.org/En/A_Brief_Guide_to_Mozilla_Preferences
1.97 +.. _mozprofile.profile: https://github.com/mozilla/mozbase/tree/master/mozprofile/mozprofile/profile.py
1.98 +.. _AddonManager: https://github.com/mozilla/mozbase/tree/master/mozprofile/mozprofile/addons.py
1.99 +.. _here: https://github.com/mozilla/mozbase/blob/master/mozprofile/mozprofile/permissions.py
1.100 +.. _ProfileManager: https://developer.mozilla.org/en/Profile_Manager
1.101 +.. _python-profilemanager: http://k0s.org/mozilla/hg/profilemanager/
1.102 +.. _documentation: http://support.mozilla.com/en-US/kb/Profiles
