update

Author: SilverRainZ

src/sphinxnotes/any/view.py

@@ -0,0 +1,143 @@
+"""
+sphinxnotes.any.directives
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Directive implementations.
+
+:copyright: Copyright 2021 Shengyu Zhang
+:license: BSD, see LICENSE for details.
+"""
+
+from __future__ import annotations
+from typing import Type
+
+from docutils import nodes
+from docutils.nodes import Node, Element, fully_normalize_name
+from docutils.statemachine import StringList
+from docutils.parsers.rst import directives
+from sphinx import addnodes
+from sphinx.util.docutils import SphinxDirective
+from sphinx.util.nodes import make_id, nested_parse_with_titles
+from sphinx.util import logging
+
+from .objects import Schema, Object
+
+logger = logging.getLogger(__name__)
+
+
+def anchor(arg: str):
+    return directives.choice(arg, ['no', 'section', 'objdesc'])
+
+class ViewDirective(SphinxDirective):
+    # Member of parent
+    has_content = True
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+    option_spec = {
+        'jinja': directives.unchanged,
+        'anchor': anchor,
+    }
+
+    def _fetch_data_source(self, src: str) -> dict[str, str]:
+        return self.env.current_document['sphinxnotes-any-data-src']
+
+    def _setup_nodes(
+        self, obj: Object, sectnode: Element, ahrnode: Element | None, contnode: Element
+    ) -> None:
+        """
+        Attach necessary informations to nodes and note them.
+
+        The necessary information contains: domain info, basic attributes for nodes
+        (ids, names, classes...), name of anchor, description content and so on.
+
+        :param sectnode: Section node, used as container of the whole object description
+        :param ahrnode: Anchor node, used to mark the location of object description
+        :param contnode: Content node, which contains the description content
+        """
+        # Setup anchor
+        if ahrnode is not None:
+            _, objid = self.schema.identifier_of(obj)
+            ahrid = make_id(self.env, self.state.document, prefix=objtype, term=objid)
+            ahrnode['ids'].append(ahrid)
+            # Add object name to node's names attribute.
+            # 'names' is space-separated list containing normalized reference
+            # names of an element.
+            name = self.schema.name_of(obj)
+            if isinstance(name, str):
+                ahrnode['names'].append(fully_normalize_name(name))
+            elif isinstance(name, list):
+                ahrnode['names'].extend([fully_normalize_name(x) for x in name])
+            self.state.document.note_explicit_target(ahrnode)
+            # Note object by docu fields
+            domain.note_object(
+                self.env.docname, ahrid, self.schema, obj
+            )  # FIXME: Cast to AnyDomain
+
+        # Parse description
+        nested_parse_with_titles(
+            self.state, StringList(self.schema.render_description(obj)), contnode
+        )
+
+    def _run_section(self, obj: Object) -> list[Node]:
+        # Get the title of the "section" where the directive is located
+        sectnode = self.state.parent
+        titlenode = sectnode.next_node(nodes.title)
+        if not titlenode or titlenode.parent != sectnode:
+            # Title should be direct child of section
+            msg = 'Failed to get title of current section'
+            logger.warning(msg, location=sectnode)
+            sm = nodes.system_message(
+                msg, type='WARNING', level=2, backrefs=[], source=''
+            )
+            sectnode += sm
+            title = ''
+        else:
+            title = titlenode.astext()
+        # Replace the first name "_" with section title
+        name = title + obj.name[1:]
+        # Object is immutable, so create a new one
+        obj = self.schema.object(name=name, attrs=obj.attrs, content=obj.content)
+        # NOTE: In _setup_nodes, the anchor node(ahrnode) will be noted by
+        # `note_explicit_target` for ahrnode, while `sectnode` is already noted
+        # by `note_implicit_target`.
+        # Multiple `note_xxx_target` calls to same node causes undefined behavior,
+        # so we use `titlenode` as anchor node
+        #
+        # See https://github.com/sphinx-notes/any/issues/18
+        self._setup_nodes(obj, sectnode, titlenode, sectnode)
+        # Add all content to existed section, so return nothing
+        return []
+
+    def _run_objdesc(self, obj: Object) -> list[Node]:
+        descnode = addnodes.desc()
+
+        # Generate signature node
+        title = self.schema.title_of(obj)
+        if title is None:
+            # Use non-generated object ID as replacement of title
+            idfield, objid = self.schema.identifier_of(obj)
+            title = objid if idfield is not None else None
+        if title is not None:
+            signode = addnodes.desc_signature(title, '')
+            signode += addnodes.desc_name(title, title)
+            descnode.append(signode)
+        else:
+            signode = None
+
+        # Generate content node
+        contnode = addnodes.desc_content()
+        descnode.append(contnode)
+        self._setup_nodes(obj, descnode, signode, contnode)
+        return [descnode]
+
+    def run(self) -> list[Node]:
+        obj = self._build_object()
+        if self.schema.title_of(obj) == '_':
+            # If no argument is given, or the first argument is '_',
+            # use the section title as object name and anchor,
+            # append content nodes to section node
+            return self._run_section(obj)
+        else:
+            # Else, create Sphinx ObjectDescription(sphinx.addnodes.dsec_*)
+            return self._run_objdesc(obj)