docs: add a hands-on tutorial for a blk-rq-qos crash

I've been wanting to add something like this for awhile. This also
includes some requisite Sphinx and CSS tweaks.

Signed-off-by: Omar Sandoval <[email protected]>

.pre-commit-config.yaml

@@ -9,6 +9,7 @@ repos:
     rev: 24.8.0
     hooks:
     -   id: black
+        exclude: ^docs/exts/details\.py$
 -   repo: https://github.com/pycqa/flake8
     rev: 7.1.1
     hooks:

docs/_static/custom.css

@@ -1,3 +1,8 @@
+details {
+    margin-block-start: 1em;
+    margin-block-end: 1em;
+}
+
 div.admonition {
     padding-bottom: 0;
 }
@@ -7,6 +12,20 @@ div.admonition p.admonition-title {
     font-weight: bold;
 }
 
+div.tip {
+    background-color: #DFD;
+    border-color: #ACA;
+}
+
+div.scroll-y pre {
+    max-height: 20em;
+    overflow-y: auto;
+}
+
+div.tutorial pre {
+    border-left: 5px solid #5A5;
+}
+
 @media screen and (min-width: 875px) {
     div.document {
         width: 100%;

docs/conf.py

@@ -7,6 +7,7 @@
 master_doc = "index"
 
 extensions = [
+    "details",
     "drgndoc.ext",
     "linuxsrc",
     "setuptools_config",

docs/exts/details.py

@@ -0,0 +1,85 @@
+# Copyright 2017-2019 by Takeshi KOMIYA
+# SPDX-License-Identifier: Apache-2.0
+# From https://pypi.org/project/sphinxcontrib-details-directive/, patched to
+# use the proper name for the :class: option.
+
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+from sphinx.transforms.post_transforms import SphinxPostTransform
+from sphinx.util.nodes import NodeMatcher
+
+
+class details(nodes.Element, nodes.General):
+    pass
+
+
+class summary(nodes.TextElement, nodes.General):
+    pass
+
+
+def visit_details(self, node):
+    if node.get('opened'):
+        self.body.append(self.starttag(node, 'details', open="open"))
+    else:
+        self.body.append(self.starttag(node, 'details'))
+
+
+def depart_details(self, node):
+    self.body.append('</details>')
+
+
+def visit_summary(self, node):
+    self.body.append(self.starttag(node, 'summary'))
+
+
+def depart_summary(self, node):
+    self.body.append('</summary>')
+
+
+class DetailsDirective(Directive):
+    required_arguments = 1
+    final_argument_whitespace = True
+    has_content = True
+    option_spec = {
+        'class': directives.class_option,
+        'name': directives.unchanged,
+        'open': directives.flag,
+    }
+
+    def run(self):
+        admonition = nodes.container('',
+                                     classes=self.options.get('class', []),
+                                     opened='open' in self.options,
+                                     type='details')
+        textnodes, messages = self.state.inline_text(self.arguments[0],
+                                                     self.lineno)
+        admonition += nodes.paragraph(self.arguments[0], '', *textnodes)
+        admonition += messages
+        self.state.nested_parse(self.content, self.content_offset, admonition)
+        self.add_name(admonition)
+        return [admonition]
+
+
+class DetailsTransform(SphinxPostTransform):
+    default_priority = 200
+    builders = ('html',)
+
+    def run(self):
+        matcher = NodeMatcher(nodes.container, type='details')
+        for node in self.document.traverse(matcher):
+            newnode = details(**node.attributes)
+            newnode += summary('', '', *node[0])
+            newnode.extend(node[1:])
+            node.replace_self(newnode)
+
+
+def setup(app):
+    app.add_node(details, html=(visit_details, depart_details))
+    app.add_node(summary, html=(visit_summary, depart_summary))
+    app.add_directive('details', DetailsDirective)
+    app.add_post_transform(DetailsTransform)
+
+    return {
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

docs/index.rst

@@ -34,6 +34,7 @@ Table of Contents
     api_reference
     helpers
     support_matrix
+    tutorials
     case_studies
     getting_debugging_symbols
     release_highlights

docs/tutorials.rst

@@ -0,0 +1,9 @@
+Tutorials
+=========
+
+Hands-on tutorials for learning how to use drgn.
+
+.. toctree::
+   :maxdepth: 1
+
+   tutorials/blk_rq_qos_crash.rst