HACKING.md

   1 Guidelines for Code Modification
   2 ================================
   3
   4 Coding Style
   5 ------------
   6
   7 * Use syntax compatible to both python 2.6+ and 3.1+.
   8 * Use docstrings with pydoc in mind
   9 * Follow the style guide for python code:
  10     http://www.python.org/dev/peps/pep-0008/
  11 * Test the code with "doctest" where it makes sense
  12
  13
  14 Patches
  15 -------
  16
  17 Send patches, created with "git format-patch", to the email address
  18
  19     hut@hut.pm
  20
  21 or open a pull request on GitHub.
  22
  23
  24 Version Numbering
  25 -----------------
  26
  27 Three numbers, A.B.C, where
  28 * A changes on a rewrite
  29 * B changes when major configuration incompatibilities occur
  30 * C changes with each release
  31
  32
  33 Starting Points
  34 ---------------
  35
  36 Good places to read about ranger internals are:
  37
  38 * ranger/core/actions.py
  39 * ranger/container/fsobject.py
  40
  41 About the UI:
  42
  43 * ranger/gui/widgets/browsercolumn.py
  44 * ranger/gui/widgets/browserview.py
  45 * ranger/gui/ui.py
  46
  47
  48 Common Changes
  49 ==============
  50
  51 Adding options
  52 --------------
  53
  54 * Add a default value in rc.conf, along with a comment that describes the option.
  55 * Add the option to the ALLOWED_SETTINGS dictionary in the file
  56   ranger/container/settings.py.  Make sure to sort in the new entry
  57   alphabetically.
  58 * Add an entry in the man page by editing doc/ranger.pod, then rebuild the man
  59   page by running "make man" in the ranger root directory
  60
  61 The setting is now accessible with self.settings.my_option, assuming self is a
  62 subclass of ranger.core.shared.SettingsAware.
  63
  64
  65 Adding colorschemes
  66 -------------------
  67
  68 * Copy ranger/colorschemes/default.py to ranger/colorschemes/myscheme.py
  69   and modify it according to your needs.  Alternatively, create a subclass of
  70   ranger.colorschemes.default.Default and override the "use" method, as it is
  71   done in the "Jungle" colorscheme.
  72
  73 * Add this line to your ~/.config/ranger/rc.conf:
  74
  75     set colorscheme myscheme
  76
  77
  78 Change which programs start which file types
  79 --------------------------------------------
  80
  81 Edit the configuration file ~/.config/ranger/rifle.conf.  The default one can
  82 be obtained by running "ranger --copy-config rifle".
  83
  84
  85 Change which file extensions have which mime type
  86 -------------------------------------------------
  87
  88 Modify ranger/data/mime.types.  You may also add your own entries to ~/.mime.types
  89
  90
  91 Change which files are previewed in the auto preview
  92 ----------------------------------------------------
  93
  94 In ranger/container/file.py, change the constant PREVIEW_BLACKLIST