Source code for pyquickhelper.sphinxext.sphinx_cmdref_extension

# -*- coding: utf-8 -*-
"""
Defines a :epkg:`sphinx` extension to keep track of *cmd*.


:githublink:`%|py|6`
"""
from io import StringIO
from docutils import nodes
import sphinx
from sphinx.util import logging
from docutils.parsers.rst import directives
from ..loghelper import run_script, noLOG
from .sphinx_blocref_extension import BlocRef, process_blocrefs_generic, BlocRefList, process_blocref_nodes_generic
from .import_object_helper import import_object


[docs]class cmdref_node(nodes.admonition): """ defines ``cmdref`` node :githublink:`%|py|19` """ pass
[docs]class cmdreflist(nodes.General, nodes.Element): """ defines ``cmdreflist`` node :githublink:`%|py|26` """ pass
[docs]class CmdRef(BlocRef): """ A ``cmdref`` entry, displayed in the form of an admonition. It is used to reference a script a module is added as a command line. It takes the following options: * *title*: a title for the bloc * *tag*: a tag to have several categories of blocs, if not specified, it will be equal to *cmd* * *lid* or *label*: a label to refer to * *index*: to add an additional entry to the index (comma separated) * *name*: command line name, if populated, the directive displays the output of ``name --help``. * *path*: used if the command line startswith ``-m`` It works the same way as :class:`BlocRef <pyquickhelper.sphinxext.sphinx_blocref_extension.BlocRef>`. The command line can be something like ``-m <module> <command> ...``. The extension will call :epkg:`python` in a separate process. .. todoext:: :title: cmdref does not display anything if the content is empty. :tag: bug :issue: 51 :githublink:`%|py|52` """ node_class = cmdref_node name_sphinx = "cmdref" option_spec = dict(cmd=directives.unchanged, path=directives.unchanged, **BlocRef.option_spec)
[docs] def run(self): """ calls run from :class:`BlocRef <pyquickhelper.sphinxext.sphinx_blocref_extension.BlocRef>` and add index entries by default :githublink:`%|py|64` """ if 'title' not in self.options: lineno = self.lineno env = self.state.document.settings.env if hasattr( self.state.document.settings, "env") else None docname = None if env is None else env.docname raise KeyError("unable to find 'title' in node {0}\n File \"{1}\", line {2}\nkeys: {3}".format( str(self.__class__), docname, lineno, list(self.options.keys()))) title = self.options['title'] if "tag" not in self.options: self.options["tag"] = "cmd" if "index" not in self.options: self.options["index"] = title else: self.options["index"] += "," + title path = self.options.get('path', None) res, cont = BlocRef.private_run(self, add_container=True) name = self.options.get("cmd", None) if name is not None and len(name) > 0: self.reporter = self.state.document.reporter try: source, lineno = self.reporter.get_source_and_line(self.lineno) except AttributeError: source = lineno = None # object name if name.startswith("-m"): # example: -m pyquickhelper clean_files --help out, err = run_script( name, fLOG=noLOG, wait=True, change_path=path) if err: lines = err.split('\n') err = [] for line in lines: if 'is already registered, it will be overridden' in line: continue err.append(line) err = "\n".join(err).strip('\n\r\t ') if err: out = "--SCRIPT--{}\n--OUT--\n{}\n--ERR--\n{}\n--PATH--\n{}".format( name, out, err, path) logger = logging.getLogger("CmdRef") logger.warning("[CmdRef] cmd failed '{0}'".format(name)) elif out in (None, ''): out = "--SCRIPT--{}\n--EMPTY OUTPUT--\n--PATH--\n{}".format( name, path) logger = logging.getLogger("CmdRef") logger.warning("[CmdRef] cmd empty '{0}'".format(name)) content = "python " + name cont += nodes.paragraph('<<<', '<<<') pout = nodes.literal_block(content, content) cont += pout cont += nodes.paragraph('>>>', '>>>') pout = nodes.literal_block(out, out) cont += pout else: if ":" not in name: logger = logging.getLogger("CmdRef") logger.warning( "[CmdRef] cmd '{0}' should contain ':': <full_function_name>:<cmd_name> as specified in the setup.".format(name)) if lineno is not None: logger.warning( ' File "{0}", line {1}'.format(source, lineno)) # example: pyquickhelper.cli.pyq_sync_cli:pyq_sync spl = name.strip("\r\n\t ").split(":") if len(spl) != 2: logger = logging.getLogger("CmdRef") logger.warning( "[CmdRef] cmd(*= '{0}' should contain ':': <full_function_name>:<cmd_name> as specified in the setup.".format(name)) if lineno is not None: logger.warning( ' File "{0}", line {1}'.format(source, lineno)) # rename the command line if "=" in spl[0]: name_cmd, fullname = spl[0].split('=') name_fct = spl[1] else: fullname, name_cmd = spl name_fct = name_cmd name_fct = name_fct.strip() fullname = fullname.strip() name_cmd = name_cmd.strip() fullname = "{0}.{1}".format(fullname, name_fct) try: obj, name = import_object(fullname, kind="function") except ImportError: logger = logging.getLogger("CmdRef") logger.warning( "[CmdRef] unable to import '{0}'".format(fullname)) if lineno is not None: logger.warning( ' File "{0}", line {1}'.format(source, lineno)) obj = None if obj is not None: stio = StringIO() def local_print(*li): "local function" stio.write(" ".join(str(_) for _ in li) + "\n") obj(args=['--help'], fLOG=local_print) content = "{0} --help".format(name_cmd) pout = nodes.paragraph(content, content) cont += pout content = stio.getvalue() if len(content) == 0: logger = logging.getLogger("CmdRef") logger.warning( "[CmdRef] empty output for '{0}'".format(fullname)) if lineno is not None: logger.warning( ' File "{0}", line {1}'.format(source, lineno)) out = "--SCRIPT--{}\n--EMPTY OUTPUT--\n--PATH--\n{}".format( name, path) logger = logging.getLogger("CmdRef") logger.warning("[CmdRef] cmd empty '{0}'".format(name)) else: start = 'usage: ' + name_fct if content.startswith(start): content = "usage: {0}{1}".format( name_cmd, content[len(start):]) pout = nodes.literal_block(content, content) cont += pout return res
[docs]def process_cmdrefs(app, doctree): """ Collect all cmdrefs in the environment this is not done in the directive itself because it some transformations must have already been run, e.g. substitutions. :githublink:`%|py|204` """ process_blocrefs_generic( app, doctree, bloc_name="cmdref", class_node=cmdref_node)
[docs]class CmdRefList(BlocRefList): """ A list of all *cmdref* entries, for a specific tag. * tag: a tag to have several categories of *cmdref* * contents: add a bullet list with links to added blocs :githublink:`%|py|215` """ name_sphinx = "cmdreflist" node_class = cmdreflist
[docs] def run(self): """ calls run from :class:`BlocRefList <pyquickhelper.sphinxext.sphinx_blocref_extension.BlocRefList>` and add default tag if not present :githublink:`%|py|222` """ if "tag" not in self.options: self.options["tag"] = "cmd" return BlocRefList.run(self)
[docs]def process_cmdref_nodes(app, doctree, fromdocname): """ process_cmdref_nodes :githublink:`%|py|231` """ process_blocref_nodes_generic(app, doctree, fromdocname, class_name='cmdref', entry_name="cmdmes", class_node=cmdref_node, class_node_list=cmdreflist)
[docs]def purge_cmdrefs(app, env, docname): """ purge_cmdrefs :githublink:`%|py|240` """ if not hasattr(env, 'cmdref_all_cmdrefs'): return env.cmdref_all_cmdrefs = [cmdref for cmdref in env.cmdref_all_cmdrefs if cmdref['docname'] != docname]
[docs]def merge_cmdref(app, env, docnames, other): """ merge_cmdref :githublink:`%|py|250` """ if not hasattr(other, 'cmdref_all_cmdrefs'): return if not hasattr(env, 'cmdref_all_cmdrefs'): env.cmdref_all_cmdrefs = [] env.cmdref_all_cmdrefs.extend(other.cmdref_all_cmdrefs)
[docs]def visit_cmdref_node(self, node): """ visit_cmdref_node :githublink:`%|py|261` """ self.visit_admonition(node)
[docs]def depart_cmdref_node(self, node): """ *depart_cmdref_node*, see `sphinx/writers/html.py <https://github.com/sphinx-doc/sphinx/blob/master/sphinx/writers/html.py>`_. :githublink:`%|py|269` """ self.depart_admonition(node)
[docs]def visit_cmdreflist_node(self, node): """ visit_cmdreflist_node see `sphinx/writers/html.py <https://github.com/sphinx-doc/sphinx/blob/master/sphinx/writers/html.py>`_. :githublink:`%|py|277` """ self.visit_admonition(node)
[docs]def depart_cmdreflist_node(self, node): """ *depart_cmdref_node* :githublink:`%|py|284` """ self.depart_admonition(node)
[docs]def setup(app): """ setup for ``cmdref`` (sphinx) :githublink:`%|py|291` """ if hasattr(app, "add_mapping"): app.add_mapping('cmdref', cmdref_node) app.add_mapping('cmdreflist', cmdreflist) app.add_config_value('cmdref_include_cmdrefs', True, 'html') app.add_config_value('cmdref_link_only', False, 'html') app.add_node(cmdreflist, html=(visit_cmdreflist_node, depart_cmdreflist_node), epub=(visit_cmdreflist_node, depart_cmdreflist_node), elatex=(visit_cmdreflist_node, depart_cmdreflist_node), latex=(visit_cmdreflist_node, depart_cmdreflist_node), text=(visit_cmdreflist_node, depart_cmdreflist_node), md=(visit_cmdreflist_node, depart_cmdreflist_node), rst=(visit_cmdreflist_node, depart_cmdreflist_node)) app.add_node(cmdref_node, html=(visit_cmdref_node, depart_cmdref_node), epub=(visit_cmdref_node, depart_cmdref_node), elatex=(visit_cmdref_node, depart_cmdref_node), latex=(visit_cmdref_node, depart_cmdref_node), text=(visit_cmdref_node, depart_cmdref_node), md=(visit_cmdref_node, depart_cmdref_node), rst=(visit_cmdref_node, depart_cmdref_node)) app.add_directive('cmdref', CmdRef) app.add_directive('cmdreflist', CmdRefList) app.connect('doctree-read', process_cmdrefs) app.connect('doctree-resolved', process_cmdref_nodes) app.connect('env-purge-doc', purge_cmdrefs) app.connect('env-merge-info', merge_cmdref) return {'version': sphinx.__display_version__, 'parallel_read_safe': True}