Bug 1427213: Clean up docstrings in mozpack.path; r=glandium

MozReview-Commit-ID: 91cm9XJROy0

--HG--
extra : rebase_source : 1ab1ce1063096651f9095fd221656c852b6892d8

python/mozbuild/mozpack/path.py

@@ -2,23 +2,23 @@
 # License, v. 2.0. If a copy of the MPL was not distributed with this
 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
+'''
+Like :py:mod:`os.path`, with a reduced set of functions, and with normalized path
+separators (always use forward slashes).
+Also contains a few additional utilities not found in :py:mod:`os.path`.
+'''
+
 from __future__ import absolute_import
 
 import posixpath
 import os
 import re
 
-'''
-Like os.path, with a reduced set of functions, and with normalized path
-separators (always use forward slashes).
-Also contains a few additional utilities not found in os.path.
-'''
-
 
 def normsep(path):
     '''
     Normalize path separators, by using forward slashes instead of whatever
-    os.sep is.
+    :py:const:`os.sep` is.
     '''
     if os.sep != '/':
         path = path.replace(os.sep, '/')
@@ -67,17 +67,19 @@ def splitext(path):
 def split(path):
     '''
     Return the normalized path as a list of its components.
-        split('foo/bar/baz') returns ['foo', 'bar', 'baz']
+
+        ``split('foo/bar/baz')`` returns ``['foo', 'bar', 'baz']``
     '''
     return normsep(path).split('/')
 
 
 def basedir(path, bases):
     '''
-    Given a list of directories (bases), return which one contains the given
+    Given a list of directories (`bases`), return which one contains the given
     path. If several matches are found, the deepest base directory is returned.
-        basedir('foo/bar/baz', ['foo', 'baz', 'foo/bar']) returns 'foo/bar'
-        ('foo' and 'foo/bar' both match, but 'foo/bar' is the deepest match)
+
+        ``basedir('foo/bar/baz', ['foo', 'baz', 'foo/bar'])`` returns ``'foo/bar'``
+        (`'foo'` and `'foo/bar'` both match, but `'foo/bar'` is the deepest match)
     '''
     path = normsep(path)
     bases = [normsep(b) for b in bases]
@@ -90,20 +92,28 @@ def basedir(path, bases):
 
 re_cache = {}
 
+
 def match(path, pattern):
     '''
     Return whether the given path matches the given pattern.
     An asterisk can be used to match any string, including the null string, in
     one part of the path:
-        'foo' matches '*', 'f*' or 'fo*o'
+
+        ``foo`` matches ``*``, ``f*`` or ``fo*o``
+
     However, an asterisk matching a subdirectory may not match the null string:
-        'foo/bar' does *not* match 'foo/*/bar'
+
+        ``foo/bar`` does *not* match ``foo/*/bar``
+
     If the pattern matches one of the ancestor directories of the path, the
     patch is considered matching:
-        'foo/bar' matches 'foo'
+
+        ``foo/bar`` matches ``foo``
+
     Two adjacent asterisks can be used to match files and zero or more
     directories and subdirectories.
-        'foo/bar' matches 'foo/**/bar', or '**/bar'
+
+        ``foo/bar`` matches ``foo/**/bar``, or ``**/bar``
     '''
     if not pattern:
         return True
@@ -118,7 +128,7 @@ def match(path, pattern):
 
 def rebase(oldbase, base, relativepath):
     '''
-    Return relativepath relative to base instead of oldbase.
+    Return `relativepath` relative to `base` instead of `oldbase`.
     '''
     if base == oldbase:
         return relativepath

tools/lint/flake8.yml

@@ -11,6 +11,7 @@ flake8:
         - python/mach
         - python/mach_commands.py
         - python/mozboot
+        - python/mozbuild/mozpack/path.py
         - python/mozlint
         - python/mozterm
         - python/mozversioncontrol