Update sphinx for Python 3.13 support (#2503)

* Fix sphinx warnings in docstrings

* Update sphinx for Python 3.13 support

Could not import extension sphinx.builders.epub3 (exception: No module named 'imghdr')

`imghdr` was removed in Python 3.13.

docs/requirements.txt

@@ -2,7 +2,8 @@ capstone
 coverage[toml]
 python-dateutil
 doc2dash
-docutils<0.18
+docutils<0.18; python_version<'3'
+docutils>=0.18; python_version>='3'
 intervaltree
 isort
 mako>=1.0.0
@@ -18,6 +19,6 @@ psutil
 requests>=2.5.1
 ropgadget>=5.3
 sphinx==1.8.6; python_version<'3'
-sphinx>=4.5.0; python_version>='3'
+sphinx>=7.0.0; python_version>='3'
 sphinx_rtd_theme
 sphinxcontrib-autoprogram<=0.1.5

docs/source/protocols.rst

@@ -1 +1,10 @@
+.. testsetup:: *
 
+   from pwn import *
+
+
+:mod:`pwnlib.protocols.adb` --- Protocol implementations
+========================================================
+
+.. automodule:: pwnlib.protocols.adb
+   :members:

docs/source/shellcraft/riscv64.rst

@@ -4,16 +4,16 @@
    context.clear(arch='riscv64')
 
 :mod:`pwnlib.shellcraft.riscv64` --- Shellcode for RISCV64
-===========================================================
+==========================================================
 
 :mod:`pwnlib.shellcraft.riscv64`
--------------------------------
+--------------------------------
 
 .. automodule:: pwnlib.shellcraft.riscv64
    :members:
 
 :mod:`pwnlib.shellcraft.riscv64.linux`
----------------------------------------
+--------------------------------------
 
 .. automodule:: pwnlib.shellcraft.riscv64.linux
    :members:

docs/source/windbg.rst

@@ -3,7 +3,7 @@
     from pwn import *
 
 :mod:`pwnlib.windbg` --- Working with WinDbg
-======================================
+============================================
 
 .. automodule:: pwnlib.windbg
    :members:

pwnlib/elf/corefile.py

@@ -238,8 +238,8 @@ class Corefile(ELF):
     Registers can be accessed directly, e.g. via ``core_obj.eax`` and enumerated
     via :data:`Corefile.registers`.
 
-    Memory can be accessed directly via :meth:`.read` or :meth:`.write`, and also
-    via :meth:`.pack` or :meth:`.unpack` or even :meth:`.string`.
+    Memory can be accessed directly via :meth:`pwnlib.elf.elf.ELF.read` or :meth:`pwnlib.elf.elf.ELF.write`, and also
+    via :meth:`pwnlib.elf.elf.ELF.pack` or :meth:`pwnlib.elf.elf.ELF.unpack` or even :meth:`.string`.
 
     Arguments:
         core: Path to the core file.  Alternately, may be a :class:`.process` instance,
@@ -376,8 +376,8 @@ class Corefile(ELF):
         >>> core.exe.data[0:4]
         b'\x7fELF'
 
-        It also supports all of the features of :class:`ELF`, so you can :meth:`.read`
-        or :meth:`.write` or even the helpers like :meth:`.pack` or :meth:`.unpack`.
+        It also supports all of the features of :class:`ELF`, so you can :meth:`pwnlib.elf.elf.ELF.read`
+        or :meth:`pwnlib.elf.elf.ELF.write` or even the helpers like :meth:`pwnlib.elf.elf.ELF.pack` or :meth:`pwnlib.elf.elf.ELF.unpack`.
 
         Don't forget to call :meth:`.ELF.save` to save the changes to disk.
 

pwnlib/elf/elf.py

@@ -2350,7 +2350,7 @@ def disable_nx(self):
 
     @staticmethod
     def set_runpath(exepath, runpath):
-        r"""set_runpath(str, str) -> ELF
+        r"""set_runpath(exepath, runpath) -> ELF
 
         Patches the RUNPATH of the ELF to the given path using the `patchelf utility <https://github.com/NixOS/patchelf>`_.
 
@@ -2385,7 +2385,7 @@ def set_runpath(exepath, runpath):
 
     @staticmethod
     def set_interpreter(exepath, interpreter_path):
-        r"""set_interpreter(str, str) -> ELF
+        r"""set_interpreter(exepath, interpreter_path) -> ELF
 
         Patches the interpreter of the ELF to the given binary using the `patchelf utility <https://github.com/NixOS/patchelf>`_.
 
@@ -2419,7 +2419,7 @@ def set_interpreter(exepath, interpreter_path):
 
     @staticmethod
     def patch_custom_libraries(exe_path, custom_library_path, create_copy=True, suffix='_remotelibc'):
-        r"""patch_custom_libraries(str, str, bool, str) -> ELF
+        r"""patch_custom_libraries(exe_path, custom_library_path, create_copy=True, suffix='_remotelibc') -> ELF
 
         Looks for the interpreter binary in the given path and patches the binary to use
         it if available. Also patches the RUNPATH to the given path using the `patchelf utility <https://github.com/NixOS/patchelf>`_.

pwnlib/libcdb.py

@@ -766,12 +766,12 @@ def search_by_libs_id(libs_id, unstrip=True, offline_only=False):
 
     Arguments:
         libs_id(str):
-            Libs ID (e.g. 'libc6_...') of the library
+            Libs ID (e.g. ``'libc6_...'``) of the library
         unstrip(bool):
             Try to fetch debug info for the libc and apply it to the downloaded file.
         offline_only(bool):
-            When pass `offline_only=True`, restricts search mode to offline sources only,
-            disable online lookup. Defaults to `False`, and enable both offline and online providers.
+            When pass ``offline_only=True``, restricts search mode to offline sources only,
+            disable online lookup. Defaults to :const:`False`, and enable both offline and online providers.
 
     Returns:
         Path to the downloaded library on disk, or :const:`None`.

pwnlib/tubes/process.py

@@ -888,8 +888,10 @@ def maps(self):
         """maps() -> [mapping]
 
         Returns a list of process mappings.
+        
         A mapping object has the following fields:
             addr, address (addr alias), start (addr alias), end, size, perms, path, rss, pss, shared_clean, shared_dirty, private_clean, private_dirty, referenced, anonymous, swap
+
         perms is a permissions object, with the following fields:
             read, write, execute, private, shared, string
 
@@ -917,24 +919,25 @@ def maps(self):
             >>> checker_arr == [True] * len(proc_maps) * 5
             True
 
-        """
-
-        """
         Useful information about this can be found at: https://man7.org/linux/man-pages/man5/proc.5.html
         specifically the /proc/pid/maps section.
 
-        memory_maps() returns a list of pmmap_ext objects
+        memory_maps() returns a list of pmmap_ext objects. The definition (from psutil/_pslinux.py) is:
+
+        .. code-block:: python
 
-        The definition (from psutil/_pslinux.py) is:
-        pmmap_grouped = namedtuple(
-            'pmmap_grouped',
-            ['path', 'rss', 'size', 'pss', 'shared_clean', 'shared_dirty',
-            'private_clean', 'private_dirty', 'referenced', 'anonymous', 'swap'])
-        pmmap_ext = namedtuple(
-            'pmmap_ext', 'addr perms ' + ' '.join(pmmap_grouped._fields))
+            pmmap_grouped = namedtuple(
+                'pmmap_grouped',
+                ['path', 'rss', 'size', 'pss', 'shared_clean', 'shared_dirty',
+                'private_clean', 'private_dirty', 'referenced', 'anonymous', 'swap'])
+            pmmap_ext = namedtuple(
+                'pmmap_ext', 'addr perms ' + ' '.join(pmmap_grouped._fields))
 
             
         Here is an example of a pmmap_ext entry: 
+
+        .. code-block:: python
+
             pmmap_ext(addr='15555551c000-155555520000', perms='r--p', path='[vvar]', rss=0, size=16384, pss=0, shared_clean=0, shared_dirty=0, private_clean=0, private_dirty=0, referenced=0, anonymous=0, swap=0)
         """
 

pwnlib/tubes/tube.py

@@ -1088,12 +1088,12 @@ def upload_manually(self, data, target_path = './payload', prompt = b'$', chunk_
         The file is uploaded in base64-encoded chunks by appending to a file
         and then decompressing it:
 
-        ```
-        loop:
-            echo <chunk> | base64 -d >> <target_path>.<compression>
-        <compression> -d -f <target_path>.<compression>
-        chmod <chmod_flags> <target_path>
-        ```
+        .. code-block::
+
+            loop:
+                echo <chunk> | base64 -d >> <target_path>.<compression>
+            <compression> -d -f <target_path>.<compression>
+            chmod <chmod_flags> <target_path>
 
         It is assumed that a `base64` command is available on the target system.
         When ``compression`` is ``auto`` the best compression utility available