Merge remote-tracking branch '6.0/stage' into 'master'

README.rst

@@ -38,9 +38,11 @@ scripting in Python. For example, you can debug the Linux kernel:
 Although other debuggers like `GDB <https://www.gnu.org/software/gdb/>`_ have
 scripting support, drgn aims to make scripting as natural as possible so that
 debugging feels like coding. This makes it well-suited for introspecting the
-complex, inter-connected state in large programs. It is also designed as a
-library that can be used to build debugging and introspection tools; see the
-official `tools <https://github.com/osandov/drgn/tree/main/tools>`_.
+complex, inter-connected state in large programs.
+
+Additionally, drgn is designed as a library that can be used to build debugging
+and introspection tools; see the official `tools
+<https://github.com/osandov/drgn/tree/main/tools>`_.
 
 drgn was developed at `Meta <https://opensource.fb.com/>`_ for debugging the
 Linux kernel (as an alternative to the `crash
@@ -115,12 +117,22 @@ From Source
 To get the development version of drgn, you will need to build it from source.
 First, install dependencies:
 
-* Fedora/RHEL/CentOS
+* Fedora
+
+  .. code-block:: console
+
+      $ sudo dnf install autoconf automake elfutils-devel gcc git libkdumpfile-devel libtool make pkgconf python3 python3-devel python3-pip python3-setuptools
+
+* RHEL/CentOS
 
   .. code-block:: console
 
       $ sudo dnf install autoconf automake elfutils-devel gcc git libtool make pkgconf python3 python3-devel python3-pip python3-setuptools
 
+  Optionally, install ``libkdumpfile-devel`` from EPEL on RHEL/CentOS >= 8 or
+  install `libkdumpfile <https://github.com/ptesarik/libkdumpfile>`_ from
+  source if you want support for the makedumpfile format.
+
   Replace ``dnf`` with ``yum`` for RHEL/CentOS < 8.
 
 * Debian/Ubuntu
@@ -129,17 +141,18 @@ First, install dependencies:
 
       $ sudo apt-get install autoconf automake gcc git liblzma-dev libelf-dev libdw-dev libtool make pkgconf python3 python3-dev python3-pip python3-setuptools zlib1g-dev
 
+  Optionally, install libkdumpfile from source if you want support for the
+  makedumpfile format.
+
 * Arch Linux
 
   .. code-block:: console
 
       $ sudo pacman -S --needed autoconf automake gcc git libelf libtool make pkgconf python python-pip python-setuptools
 
   Optionally, install `libkdumpfile
-  <https://github.com/ptesarik/libkdumpfile>`_ if you want support for the
-  `makedumpfile <https://github.com/makedumpfile/makedumpfile>`_ compressed
-  kernel core dump format. ``libkdumpfile`` is currently only packaged on
-  Fedora and EPEL. For other distributions, you must install it manually.
+  <https://aur.archlinux.org/packages/libkdumpfile/>`_ from the AUR or from
+  source if you want support for the makedumpfile format.
 
 * openSUSE
 

docs/conf.py

@@ -36,7 +36,7 @@
 html_theme = "alabaster"
 
 html_theme_options = {
-    "description": "Debugger-as-a-library",
+    "description": "Programmable debugger",
     "logo": "logo.png",
     "logo_name": True,
     "logo_text_align": "center",

docs/exts/drgndoc/format.py

@@ -2,7 +2,6 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 
 import ast
-import re
 from typing import Any, List, Optional, Pattern, Sequence, Tuple, cast
 
 from drgndoc.namespace import BoundNode, Namespace, ResolvedNode
@@ -39,8 +38,9 @@ def __init__(
         self._context_class = context_class
         self._parts: List[str] = []
 
-    def visit(self, node: ast.AST, rst: bool = True) -> str:
+    def visit(self, node: ast.AST, rst: bool, qualify_typing: bool) -> str:
         self._rst = rst
+        self._qualify_typing = qualify_typing
         super().visit(node)
         ret = "".join(self._parts)
         self._parts.clear()
@@ -93,7 +93,7 @@ def _append_resolved_name(self, name: str) -> None:
                 break
 
         title = target
-        if title.startswith("typing."):
+        if not self._qualify_typing and title.startswith("typing."):
             title = title[len("typing.") :]
         elif self._context_module and title.startswith(self._context_module + "."):
             title = title[len(self._context_module) + 1 :]
@@ -239,25 +239,9 @@ def _format_function_signature(
             context_class,
         )
         assert node.docstring is not None
-        docstring_lines = node.docstring.splitlines()
-
+        lines = node.docstring.splitlines()
         if rst:
-            lines = []
-            params_need_type = set()
-            params_have_type = set()
-            for line in docstring_lines:
-                lines.append("    " + line)
-                match = re.match(r":(param|type)\s+([a-zA-Z0-9_]+):", line)
-                if match:
-                    if match.group(1) == "param":
-                        params_need_type.add(match.group(2))
-                    else:
-                        params_have_type.add(match.group(2))
-                elif line.startswith(":rtype:"):
-                    want_rtype = False
-            params_need_type -= params_have_type
-        else:
-            lines = docstring_lines
+            lines = ["    " + line for line in lines]
 
         signature = ["("]
         need_comma = False
@@ -274,22 +258,16 @@ def visit_arg(
             signature.append(arg.arg)
 
             default_sep = "="
-            if not rst and arg.annotation:
+            if arg.annotation:
                 signature.append(": ")
-                signature.append(visitor.visit(arg.annotation, False))
+                signature.append(visitor.visit(arg.annotation, False, rst))
                 default_sep = " = "
 
             if default:
                 signature.append(default_sep)
-                signature.append(visitor.visit(default, False))
+                signature.append(visitor.visit(default, False, True))
             need_comma = True
 
-            if rst and arg.annotation and arg.arg in params_need_type:
-                if need_blank_line:
-                    lines.append("")
-                    need_blank_line = False
-                lines.append(f"    :type {arg.arg}: {visitor.visit(arg.annotation)}")
-
         posonlyargs = getattr(node.args, "posonlyargs", [])
         num_posargs = len(posonlyargs) + len(node.args.args)
         for i, arg in enumerate(posonlyargs + node.args.args):
@@ -325,14 +303,8 @@ def visit_arg(
         signature.append(")")
 
         if want_rtype and node.returns:
-            if rst:
-                if need_blank_line:
-                    lines.append("")
-                    need_blank_line = False
-                lines.append("    :rtype: " + visitor.visit(node.returns))
-            else:
-                signature.append(" -> ")
-                signature.append(visitor.visit(node.returns, False))
+            signature.append(" -> ")
+            signature.append(visitor.visit(node.returns, False, rst))
 
         return "".join(signature), lines
 
@@ -360,7 +332,7 @@ def _format_class(
                 context_module,
                 context_class,
             )
-            bases = [visitor.visit(base, rst) for base in node.bases]
+            bases = [visitor.visit(base, rst, False) for base in node.bases]
             if lines:
                 lines.append("")
             lines.append(("    " if rst else "") + "Bases: " + ", ".join(bases))
@@ -480,8 +452,6 @@ def _format_variable(
         assert node.docstring is not None
         docstring_lines = node.docstring.splitlines()
 
-        have_vartype = any(line.startswith(":vartype:") for line in docstring_lines)
-
         visitor = _FormatVisitor(
             self._namespace,
             self._substitutions,
@@ -493,19 +463,20 @@ def _format_variable(
         if rst:
             directive = "py:attribute" if resolved.classes else "py:data"
             lines = [f".. {directive}:: {name}"]
+            if node.annotation:
+                lines.append(
+                    "    :type: " + visitor.visit(node.annotation, False, True)
+                )
             if docstring_lines:
                 lines.append("")
             for line in docstring_lines:
                 lines.append("    " + line)
-            if node.annotation and not have_vartype:
-                lines.append("")
-                lines.append("    :vartype: " + visitor.visit(node.annotation))
             return lines
         else:
-            if node.annotation and not have_vartype:
+            if node.annotation:
                 if docstring_lines:
                     docstring_lines.insert(0, "")
-                docstring_lines.insert(0, visitor.visit(node.annotation, False))
+                docstring_lines.insert(0, visitor.visit(node.annotation, False, False))
             return docstring_lines
 
     def format(

drgn/__init__.py

@@ -2,9 +2,9 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 
 """
-Scriptable debugger library
+Programmable debugger
 
-drgn is a scriptable debugger. It is built on top of Python, so if you
+drgn is a programmable debugger. It is built on top of Python, so if you
 don't know at least a little bit of Python, go learn it first.
 
 drgn supports an interactive mode and a script mode. Both are simply a