Documentation updates and fixes

- Add new callbacks documentation page covering RemoteCallbacks,
  CheckoutCallbacks, StashApplyCallbacks, and Passthrough.
- Add new enums documentation page covering all pygit2.enums classes.
- Document missing classes: RemoteHead, PushUpdate, FilterList.
- Document missing methods: Repository.load_filter_list, Repository.hashfile.
- Fix create_tag docstring showing message as optional when it is required.
- Fix Odb.read_header docstring return type.
- Fix docstring reST formatting errors in callbacks.py and enums.py.
- Update version examples in general.rst to libgit2 1.9.4.
- Fix typo in branches.rst example.
- Fix bytes/string example in objects.rst create_blob snippet.
- Add callbacks.rst and enums.rst to the documentation toctree.
- Add .docenv to .gitignore.

Fixes: #1323
Fixes: #1289

Assisted-by: Kimi-k2.6

Author: jdavid

.gitignore

@@ -239,6 +239,7 @@ pyrightconfig.json
 # custom ignore paths
 /.envrc
 /venv*
+/.docenv
 /ci/
 *.swp
 /pygit2/_libgit2.c

CHANGELOG.md

@@ -14,6 +14,8 @@
 
 - Documentation and annotation fixes
   [#410](https://github.com/libgit2/pygit2/issues/410)
+  [#1289](https://github.com/libgit2/pygit2/issues/1289)
+  [#1323](https://github.com/libgit2/pygit2/issues/1323)
   [#1333](https://github.com/libgit2/pygit2/issues/1333)
   [#1458](https://github.com/libgit2/pygit2/issues/1458)
   [#1460](https://github.com/libgit2/pygit2/pull/1460)

docs/branches.rst

@@ -35,7 +35,7 @@ Example::
     >>> # Create a local branch, branching from master
     >>> new_branch = repo.branches.local.create('new-branch', repo[master_branch.target])
 
-    >>> And delete it
+    >>> # And delete it
     >>> repo.branches.delete('new-branch')
 
 

docs/callbacks.rst

@@ -0,0 +1,40 @@
+**********************************************************************
+Callbacks
+**********************************************************************
+
+Many pygit2 operations accept callback objects. The callbacks module provides
+base classes that you can subclass to customize behavior such as progress
+reporting, credential lookup, or checkout notifications.
+
+.. contents:: Contents
+   :local:
+
+
+Remote callbacks
+================
+
+.. autoclass:: pygit2.RemoteCallbacks
+   :members:
+
+
+Checkout callbacks
+==================
+
+.. autoclass:: pygit2.CheckoutCallbacks
+   :members:
+
+
+Stash apply callbacks
+=====================
+
+.. autoclass:: pygit2.StashApplyCallbacks
+   :members:
+
+
+Passthrough
+===========
+
+Callbacks may raise :exc:`pygit2.Passthrough` to tell libgit2 to behave as if
+the callback had not been set. This is useful when a callback only wants to
+handle some cases and let libgit2 use its default behavior for the rest. See
+:doc:`general` for the exception reference.

docs/conf.py

@@ -23,7 +23,7 @@
 # author = ''
 
 # The full version, including alpha/beta/rc tags
-release = '1.19.2'
+release = '1.19.3'
 
 
 # -- General configuration ---------------------------------------------------

docs/enums.rst

@@ -0,0 +1,193 @@
+**********************************************************************
+Enums
+**********************************************************************
+
+pygit2 exposes libgit2 constants as Python enums in the :mod:`pygit2.enums`
+module. They are preferred over the top-level ``GIT_*`` integer constants.
+
+.. contents:: Contents
+   :local:
+
+
+Repository
+==========
+
+.. autoclass:: pygit2.enums.RepositoryInitFlag
+   :members:
+
+.. autoclass:: pygit2.enums.RepositoryInitMode
+   :members:
+
+.. autoclass:: pygit2.enums.RepositoryOpenFlag
+   :members:
+
+.. autoclass:: pygit2.enums.RepositoryState
+   :members:
+
+
+References and branches
+=======================
+
+.. autoclass:: pygit2.enums.BranchType
+   :members:
+
+.. autoclass:: pygit2.enums.ReferenceFilter
+   :members:
+
+.. autoclass:: pygit2.enums.ReferenceType
+   :members:
+
+.. autoclass:: pygit2.enums.ResetMode
+   :members:
+
+.. autoclass:: pygit2.enums.RevSpecFlag
+   :members:
+
+
+Objects
+=======
+
+.. autoclass:: pygit2.enums.ObjectType
+   :members:
+
+.. autoclass:: pygit2.enums.FileMode
+   :members:
+
+
+Diff
+====
+
+.. autoclass:: pygit2.enums.DeltaStatus
+   :members:
+
+.. autoclass:: pygit2.enums.DiffFind
+   :members:
+
+.. autoclass:: pygit2.enums.DiffFlag
+   :members:
+
+.. autoclass:: pygit2.enums.DiffOption
+   :members:
+
+.. autoclass:: pygit2.enums.DiffStatsFormat
+   :members:
+
+
+Status
+======
+
+.. autoclass:: pygit2.enums.FileStatus
+   :members:
+
+
+Checkout
+========
+
+.. autoclass:: pygit2.enums.CheckoutNotify
+   :members:
+
+.. autoclass:: pygit2.enums.CheckoutStrategy
+   :members:
+
+
+Merge
+=====
+
+.. autoclass:: pygit2.enums.MergeAnalysis
+   :members:
+
+.. autoclass:: pygit2.enums.MergeFavor
+   :members:
+
+.. autoclass:: pygit2.enums.MergeFileFlag
+   :members:
+
+.. autoclass:: pygit2.enums.MergeFlag
+   :members:
+
+.. autoclass:: pygit2.enums.MergePreference
+   :members:
+
+
+Blame
+=====
+
+.. autoclass:: pygit2.enums.BlameFlag
+   :members:
+
+
+Filters
+=======
+
+.. autoclass:: pygit2.enums.FilterMode
+   :members:
+
+.. autoclass:: pygit2.enums.FilterFlag
+   :members:
+
+.. autoclass:: pygit2.enums.BlobFilter
+   :members:
+
+
+Attributes
+==========
+
+.. autoclass:: pygit2.enums.AttrCheck
+   :members:
+
+
+Remotes
+=======
+
+.. autoclass:: pygit2.enums.CredentialType
+   :members:
+
+.. autoclass:: pygit2.enums.FetchPrune
+   :members:
+
+
+Submodules
+==========
+
+.. autoclass:: pygit2.enums.SubmoduleIgnore
+   :members:
+
+.. autoclass:: pygit2.enums.SubmoduleStatus
+   :members:
+
+
+Stash
+=====
+
+.. autoclass:: pygit2.enums.StashApplyProgress
+   :members:
+
+
+Revwalk
+=======
+
+.. autoclass:: pygit2.enums.SortMode
+   :members:
+
+.. autoclass:: pygit2.enums.DescribeStrategy
+   :members:
+
+
+Apply
+=====
+
+.. autoclass:: pygit2.enums.ApplyLocation
+   :members:
+
+
+Library
+=======
+
+.. autoclass:: pygit2.enums.Feature
+   :members:
+
+.. autoclass:: pygit2.enums.Option
+   :members:
+
+.. autoclass:: pygit2.enums.ConfigLevel
+   :members:

docs/filters.rst

@@ -19,6 +19,17 @@ Registering filters
 .. autofunction:: pygit2.filter_register
 .. autofunction:: pygit2.filter_unregister
 
+Loading filters
+===============
+
+.. automethod:: pygit2.Repository.load_filter_list
+
+The FilterList type
+-------------------
+
+.. autoclass:: pygit2.filter.FilterList
+   :members:
+
 Example
 =======
 

docs/general.rst

@@ -18,41 +18,41 @@ library that has been built against. The version number has a
 .. py:data:: LIBGIT2_VER_MAJOR
 
    Integer value of the major version number. For example, for the version
-   ``0.26.0``::
+   ``1.9.4``::
 
       >>> print(pygit2.LIBGIT2_VER_MAJOR)
-      0
+      1
 
 .. py:data:: LIBGIT2_VER_MINOR
 
    Integer value of the minor version number. For example, for the version
-   ``0.26.0``::
+   ``1.9.4``::
 
       >>> print(pygit2.LIBGIT2_VER_MINOR)
-      26
+      9
 
 .. py:data:: LIBGIT2_VER_REVISION
 
    Integer value of the revision version number. For example, for the version
-   ``0.26.0``::
+   ``1.9.4``::
 
       >>> print(pygit2.LIBGIT2_VER_REVISION)
-      0
+      4
 
 .. py:data:: LIBGIT2_VER
 
    Tuple value of the revision version numbers. For example, for the version
-   ``0.26.0``::
+   ``1.9.4``::
 
       >>> print(pygit2.LIBGIT2_VER)
-      (0, 26, 0)
+      (1, 9, 4)
 
 .. py:data:: LIBGIT2_VERSION
 
    The libgit2 version number as a string::
 
       >>> print(pygit2.LIBGIT2_VERSION)
-      '0.26.0'
+      '1.9.4'
 
 Options
 =========
@@ -80,3 +80,11 @@ Exception when trying to create an object (reference, etc) that already exists.
    :undoc-members:
 
 Exception when an input specification such as a reference name is invalid.
+
+.. autoexception:: pygit2.Passthrough
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Exception that can be raised from a callback to tell libgit2 to behave as if
+that callback had not been set. See :doc:`callbacks` for details.

docs/index.rst

@@ -62,9 +62,11 @@ Table of Contents
    backends
    blame
    branches
+   callbacks
    commit_log
    config
    diff
+   enums
    features
    filters
    index_file

docs/objects.rst

@@ -112,17 +112,23 @@ them to the Git object database:
 
       Example:
 
-        >>> id  = repo.create_blob('foo bar')   # Creates blob from a byte string
+        >>> id  = repo.create_blob(b'foo bar')   # Creates blob from a byte string
         >>> blob = repo[id]
         >>> blob.data
-        'foo bar'
+        b'foo bar'
 
 There are also some functions to calculate the id for a byte string without
 creating the blob object:
 
 .. autofunction:: pygit2.hash
 .. autofunction:: pygit2.hashfile
 
+To calculate the hash of a file using the repository's filtering rules (e.g.
+``core.safecrlf``), use the repository's instance method:
+
+.. automethod:: pygit2.Repository.hashfile
+   :noindex:
+
 Streaming blob content
 ----------------------