Treat warnings as errors when building documentation

doc/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -W
 SPHINXBUILD   = sphinx-build
 PAPER         =
 

doc/source/changes.rst

@@ -139,9 +139,9 @@ https://github.com/gitpython-developers/gitpython/milestone/30?closed=1
 3.0.1 - Bugfixes and performance improvements
 =============================================
 
-* Fix a `performance regression <https://github.com/gitpython-developers/GitPython/issues/906>`_ which could make certain workloads 50% slower
-* Add `currently_rebasing_on` method on `Repo`, see `the PR <https://github.com/gitpython-developers/GitPython/pull/903/files#diff-c276fc3c4df38382ec884e59657b869dR1065>`_
-* Fix incorrect `requirements.txt` which could lead to broken installations, see this `issue <https://github.com/gitpython-developers/GitPython/issues/908>`_ for details.
+* Fix a `performance regression <https://github.com/gitpython-developers/GitPython/issues/906>`__ which could make certain workloads 50% slower
+* Add `currently_rebasing_on` method on `Repo`, see `the PR <https://github.com/gitpython-developers/GitPython/pull/903/files#diff-c276fc3c4df38382ec884e59657b869dR1065>`__
+* Fix incorrect `requirements.txt` which could lead to broken installations, see this `issue <https://github.com/gitpython-developers/GitPython/issues/908>`__ for details.
 
 3.0.0 - Remove Python 2 support
 ===============================
@@ -276,6 +276,7 @@ https://github.com/gitpython-developers/GitPython/issues?q=is%3Aclosed+milestone
   the `HEAD` reference instead.
 
 * `DiffIndex.iter_change_type(...)` produces better results when diffing
+
 2.0.8 - Features and Bugfixes
 =============================
 
@@ -304,7 +305,7 @@ https://github.com/gitpython-developers/GitPython/issues?q=is%3Aclosed+milestone
   unicode path counterparts.
 * Fix: TypeError about passing keyword argument to string decode() on
   Python 2.6.
-* Feature: `setUrl API on Remotes <https://github.com/gitpython-developers/GitPython/pull/446#issuecomment-224670539>`_
+* Feature: `setUrl API on Remotes <https://github.com/gitpython-developers/GitPython/pull/446#issuecomment-224670539>`__
 
 2.0.5 - Fixes
 =============
@@ -380,13 +381,13 @@ Please note that due to breaking changes, we have to increase the major version.
   with large repositories.
 * CRITICAL: fixed incorrect `Commit` object serialization when authored or commit date had timezones which were not
   divisiblej by 3600 seconds. This would happen if the timezone was something like `+0530` for instance.
-* A list of all additional fixes can be found `on GitHub <https://github.com/gitpython-developers/GitPython/issues?q=milestone%3A%22v1.0.2+-+Fixes%22+is%3Aclosed>`_
+* A list of all additional fixes can be found `on GitHub <https://github.com/gitpython-developers/GitPython/issues?q=milestone%3A%22v1.0.2+-+Fixes%22+is%3Aclosed>`__
 * CRITICAL: `Tree.cache` was removed without replacement. It is technically impossible to change individual trees and expect their serialization results to be consistent with what *git* expects. Instead, use the `IndexFile` facilities to adjust the content of the staging area, and write it out to the respective tree objects using `IndexFile.write_tree()` instead.
 
 1.0.1 - Fixes
 =============
 
-* A list of all issues can be found `on GitHub <https://github.com/gitpython-developers/GitPython/issues?q=milestone%3A%22v1.0.1+-+Fixes%22+is%3Aclosed>`_
+* A list of all issues can be found `on GitHub <https://github.com/gitpython-developers/GitPython/issues?q=milestone%3A%22v1.0.1+-+Fixes%22+is%3Aclosed>`__
 
 1.0.0 - Notes
 =============
@@ -403,14 +404,14 @@ It follows the `semantic version scheme <http://semver.org>`_, and thus will not
 * If the git command executed during `Remote.push(...)|fetch(...)` returns with an non-zero exit code and GitPython didn't
   obtain any head-information, the corresponding `GitCommandError` will be raised. This may break previous code which expected
   these operations to never raise. However, that behavious is undesirable as it would effectively hide the fact that there
-  was an error. See `this issue <https://github.com/gitpython-developers/GitPython/issues/271>`_ for more information.
+  was an error. See `this issue <https://github.com/gitpython-developers/GitPython/issues/271>`__ for more information.
 
 * If the git executable can't be found in the PATH or at the path provided by `GIT_PYTHON_GIT_EXECUTABLE`, this is made
   obvious by throwing `GitCommandNotFound`, both on unix and on windows.
 
   - Those who support **GUI on windows** will now have to set `git.Git.USE_SHELL = True` to get the previous behaviour.
 
-* A list of all issues can be found `on GitHub <https://github.com/gitpython-developers/GitPython/issues?q=milestone%3A%22v0.3.7+-+Fixes%22+is%3Aclosed>`_
+* A list of all issues can be found `on GitHub <https://github.com/gitpython-developers/GitPython/issues?q=milestone%3A%22v0.3.7+-+Fixes%22+is%3Aclosed>`__
 
 
 0.3.6 - Features
@@ -426,11 +427,11 @@ It follows the `semantic version scheme <http://semver.org>`_, and thus will not
   * Repo.working_tree_dir now returns None if it is bare. Previously it raised AssertionError.
   * IndexFile.add() previously raised AssertionError when paths where used with bare repository, now it raises InvalidGitRepositoryError
 
-* Added `Repo.merge_base()` implementation. See the `respective issue on GitHub <https://github.com/gitpython-developers/GitPython/issues/169>`_
+* Added `Repo.merge_base()` implementation. See the `respective issue on GitHub <https://github.com/gitpython-developers/GitPython/issues/169>`__
 * `[include]` sections in git configuration files are now respected
 * Added `GitConfigParser.rename_section()`
 * Added `Submodule.rename()`
-* A list of all issues can be found `on GitHub <https://github.com/gitpython-developers/GitPython/issues?q=milestone%3A%22v0.3.6+-+Features%22+>`_
+* A list of all issues can be found `on GitHub <https://github.com/gitpython-developers/GitPython/issues?q=milestone%3A%22v0.3.6+-+Features%22+>`__
 
 0.3.5 - Bugfixes
 ================

git/index/base.py

@@ -219,7 +219,7 @@ def merge_tree(self, rhs, base=None):
         """Merge the given rhs treeish into the current index, possibly taking
         a common base treeish into account.
 
-        As opposed to the from_tree_ method, this allows you to use an already
+        As opposed to the :func:`IndexFile.from_tree` method, this allows you to use an already
         existing tree as the left side of the merge
 
         :param rhs:
@@ -830,7 +830,7 @@ def remove(self, items, working_tree=False, **kwargs):
                 to a path relative to the git repository directory containing
                 the working tree
 
-                The path string may include globs, such as *.c.
+                The path string may include globs, such as \\*.c.
 
             - Blob Object
                 Only the path portion is used in this case.
@@ -998,7 +998,7 @@ def checkout(self, paths=None, force=False, fprogress=lambda *args: None, **kwar
             If False, these will trigger a CheckoutError.
 
         :param fprogress:
-            see Index.add_ for signature and explanation.
+            see :func:`IndexFile.add` for signature and explanation.
             The provided progress information will contain None as path and item if no
             explicit paths are given. Otherwise progress information will be send
             prior and after a file has been checked out
@@ -1010,7 +1010,7 @@ def checkout(self, paths=None, force=False, fprogress=lambda *args: None, **kwar
             iterable yielding paths to files which have been checked out and are
             guaranteed to match the version stored in the index
 
-        :raise CheckoutError:
+        :raise exc.CheckoutError:
             If at least one file failed to be checked out. This is a summary,
             hence it will checkout as many files as it can anyway.
             If one of files or directories do not exist in the index

git/objects/submodule/base.py

@@ -965,7 +965,7 @@ def set_parent_commit(self, commit, check=True):
     @unbare_repo
     def config_writer(self, index=None, write=True):
         """:return: a config writer instance allowing you to read and write the data
-        belonging to this submodule into the .gitmodules file.
+            belonging to this submodule into the .gitmodules file.
 
         :param index: if not None, an IndexFile instance which should be written.
             defaults to the index of the Submodule's parent repository.

git/remote.py

@@ -827,10 +827,8 @@ def push(self, refspec=None, progress=None, **kwargs):
 
             * None to discard progress information
             * A function (callable) that is called with the progress information.
-
               Signature: ``progress(op_code, cur_count, max_count=None, message='')``.
-
-             `Click here <http://goo.gl/NPa7st>`_ for a description of all arguments
+              `Click here <http://goo.gl/NPa7st>`__ for a description of all arguments
               given to the function.
             * An instance of a class derived from ``git.RemoteProgress`` that
               overrides the ``update()`` function.

git/repo/base.py

@@ -270,9 +270,9 @@ def working_tree_dir(self):
 
     @property
     def common_dir(self):
-        """:return: The git dir that holds everything except possibly HEAD,
-        FETCH_HEAD, ORIG_HEAD, COMMIT_EDITMSG, index, and logs/ .
         """
+        :return: The git dir that holds everything except possibly HEAD,
+            FETCH_HEAD, ORIG_HEAD, COMMIT_EDITMSG, index, and logs/."""
         return self._common_dir or self.git_dir
 
     @property
@@ -988,7 +988,7 @@ def clone(self, path, progress=None, multi_options=None, **kwargs):
         :param multi_options: A list of Clone options that can be provided multiple times.  One
             option per list item which is passed exactly as specified to clone.
             For example ['--config core.filemode=false', '--config core.ignorecase',
-                         '--recurse-submodule=repo1_path', '--recurse-submodule=repo2_path']
+            '--recurse-submodule=repo1_path', '--recurse-submodule=repo2_path']
         :param kwargs:
             * odbt = ObjectDatabase Type, allowing to determine the object database
               implementation used by the returned Repo instance

git/util.py

@@ -39,11 +39,11 @@
 # Handle once test-cases are back up and running.
 # Most of these are unused here, but are for use by git-python modules so these
 # don't see gitdb all the time. Flake of course doesn't like it.
-__all__ = ("stream_copy", "join_path", "to_native_path_windows", "to_native_path_linux",
+__all__ = ["stream_copy", "join_path", "to_native_path_linux",
            "join_path_native", "Stats", "IndexFileSHA1Writer", "Iterable", "IterableList",
            "BlockingLockFile", "LockFile", 'Actor', 'get_user_id', 'assure_directory_exists',
            'RemoteProgress', 'CallableRemoteProgress', 'rmtree', 'unbare_repo',
-           'HIDE_WINDOWS_KNOWN_ERRORS')
+           'HIDE_WINDOWS_KNOWN_ERRORS']
 
 log = logging.getLogger(__name__)
 
@@ -148,6 +148,7 @@ def to_native_path_windows(path):
     def to_native_path_linux(path):
         return path.replace('\\', '/')
 
+    __all__.append("to_native_path_windows")
     to_native_path = to_native_path_windows
 else:
     # no need for any work on linux