update

Author: SilverRainZ

src/sphinxnotes/snippet/cli.py

@@ -60,9 +60,9 @@ def main(argv: list[str] = sys.argv[1:]):
         formatter_class=HelpFormatter,
         epilog=dedent("""
                                      snippet tags:
-                                       d (document)          a reST document 
-                                       s (section)           a reST section
-                                       c (code)              snippet with code blocks
+                                       d (document)          a document
+                                       s (section)           a section
+                                       c (code)              a code block
                                        * (any)               wildcard for any snippet"""),
     )
     parser.add_argument(

src/sphinxnotes/snippet/ext.py

@@ -26,7 +26,7 @@
     from collections.abc import Iterator
 
 from .config import Config
-from .snippets import Snippet, WithTitle, Document, Section
+from .snippets import Snippet, WithTitle, Document, Section, Code
 from .picker import pick
 from .cache import Cache, Item
 from .keyword import Extractor
@@ -45,6 +45,8 @@ def extract_tags(s: Snippet) -> str:
         tags += 'd'
     elif isinstance(s, Section):
         tags += 's'
+    elif isinstance(s, Code):
+        tags += 'c'
     return tags
 
 
@@ -53,14 +55,21 @@ def extract_excerpt(s: Snippet) -> str:
         return '<' + s.title.text + '>'
     elif isinstance(s, Section) and s.title is not None:
         return '[' + s.title.text + ']'
+    elif isinstance(s, Code):
+        excerpt = s.desc.astext() if s.desc else s.caption or ''  # FIXME
+        return '`' + s.language + ':' + excerpt + '`'
     return ''
 
 
 def extract_keywords(s: Snippet) -> list[str]:
     keywords = [s.docname]
-    # TODO: Deal with more snippet
     if isinstance(s, WithTitle) and s.title is not None:
         keywords.extend(extractor.extract(s.title.text, strip_stopwords=False))
+    if isinstance(s, Code):
+        if s.desc:
+            keywords.extend(extractor.extract(s.desc.astext(), strip_stopwords=False))
+        if s.caption:
+            keywords.extend(extractor.extract(s.caption, strip_stopwords=False))
     return keywords
 
 
@@ -76,7 +85,7 @@ def is_document_matched(
     return new_pats
 
 
-def is_snippet_matched(pats: dict[str, list[str]], s: [Snippet], docname: str) -> bool:
+def is_snippet_matched(pats: dict[str, list[str]], s: Snippet, docname: str) -> bool:
     """Whether the snippet's tags and docname matched by given patterns pats"""
     if '*' in pats:  # Wildcard
         for pat in pats['*']:
@@ -113,6 +122,7 @@ def on_env_get_outdated(
     removed: set[str],
 ) -> list[str]:
     # Remove purged indexes and snippetes from db
+    assert cache is not None
     for docname in removed:
         del cache[(app.config.project, docname)]
     return []
@@ -162,6 +172,7 @@ def on_doctree_resolved(app: Sphinx, doctree: nodes.document, docname: str) -> N
 
 
 def on_builder_finished(app: Sphinx, exception) -> None:
+    assert cache is not None
     cache.dump()
 
 

src/sphinxnotes/snippet/picker.py

@@ -15,7 +15,7 @@
 
 from sphinx.util import logging
 
-from .snippets import Snippet, Section, Document
+from .snippets import Snippet, Section, Document, Code
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
@@ -40,66 +40,53 @@ def pick(
         logger.debug('Skipped document with nosearch metadata')
         return []
 
-    snippets: list[tuple[Snippet, nodes.section]] = []
+    # Walk doctree and pick snippets.
+    picker = SnippetPicker(doctree)
+    doctree.walkabout(picker)
 
-    # Pick document
-    toplevel_section = doctree.next_node(nodes.section)
-    if toplevel_section:
-        snippets.append((Document(doctree), toplevel_section))
-    else:
-        logger.warning('can not pick document without child section: %s', doctree)
+    return picker.snippets
 
-    # Pick sections
-    section_picker = SectionPicker(doctree)
-    doctree.walkabout(section_picker)
-    snippets.extend(section_picker.sections)
 
-    return snippets
-
-
-class SectionPicker(nodes.SparseNodeVisitor):
+class SnippetPicker(nodes.SparseNodeVisitor):
     """Node visitor for picking snippets from document."""
 
-    #: Constant list of unsupported languages (:class:`pygments.lexers.Lexer`)
-    UNSUPPORTED_LANGUAGES: list[str] = ['default']
-
-    #: List of picked section snippets and the section it belongs to
-    sections: list[tuple[Section, nodes.section]]
+    #: List of picked snippets and the section it belongs to
+    snippets: list[tuple[Snippet, nodes.section]]
 
-    _section_has_code_block: bool
-    _section_level: int
+    #: Stack of nested sections.
+    _sections: list[nodes.section]
 
-    def __init__(self, document: nodes.document) -> None:
-        super().__init__(document)
-        self.sections = []
-        self._section_has_code_block = False
-        self._section_level = 0
+    def __init__(self, doctree: nodes.document) -> None:
+        super().__init__(doctree)
+        self.snippets = []
+        self._sections = []
 
     ###################
     # Visitor methods #
     ###################
 
     def visit_literal_block(self, node: nodes.literal_block) -> None:
-        if node['language'] in self.UNSUPPORTED_LANGUAGES:
+        try:
+            code = Code(node)
+        except ValueError as e:
+            logger.debug(f'skip {node}: {e}')
             raise nodes.SkipNode
-        self._has_code_block = True
+        self.snippets.append((code, self._sections[-1]))
 
     def visit_section(self, node: nodes.section) -> None:
-        self._section_level += 1
+        self._sections.append(node)
 
     def depart_section(self, node: nodes.section) -> None:
-        self._section_level -= 1
-        self._has_code_block = False
+        section = self._sections.pop()
+        assert section == node
 
         # Skip non-leaf section without content
         if self._is_empty_non_leaf_section(node):
             return
-        # Skip toplevel section, we generate :class:`Document` for it
-        if self._section_level == 0:
-            return
-
-        # TODO: code block
-        self.sections.append((Section(node), node))
+        if len(self._sections) == 0:
+            self.snippets.append((Document(self.document), node))
+        else:
+            self.snippets.append((Section(node), node))
 
     def unknown_visit(self, node: nodes.Node) -> None:
         pass  # Ignore any unknown node

src/sphinxnotes/snippet/snippets.py

@@ -96,15 +96,38 @@ def __init__(self, node: nodes.Node) -> None:
 
 class Code(Text):
     #: Language of code block
-    language: str
-    #: Caption of code block
-    caption: str | None
+    lang: str
+    #: Description of code block, usually the text of preceding paragraph
+    desc: nodes.paragraph | str
 
     def __init__(self, node: nodes.literal_block) -> None:
         assert isinstance(node, nodes.literal_block)
         super().__init__(node)
-        self.language = node['language']
-        self.caption = node.get('caption')
+
+        self.lang = node['language']
+
+        if isinstance(para := node.previous_sibling(), nodes.paragraph):
+            # Use the preceding paragraph as descritpion.
+            #
+            # We usually write some descritpions before a code block, for example,
+            # The ``::`` syntax is a common way to create code block::
+            #
+            #   | Foo::       | <paragraph>
+            #   |             |     Foo:
+            #   |     Bar     | <literal_block xml:space="preserve">
+            #   |             |     Bar
+            #
+            # In this case, the preceding paragraph "Foo:" is the descritpion
+            # of the code block. This convention also applies to the code,
+            # code-block, sourcecode directive.
+            self.desc = para
+        elif caption := node.get('caption'):
+            # Use caption as descritpion.
+            # In sphinx, code-block, sourcecode and code may have caption option.
+            # https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block
+            self.desc = caption
+        else:
+            raise ValueError('Lack of description: preceding paragraph or caption')
 
 
 class Title(Text):