docs/source/_ext/showfile.py

   1 # -*- coding: utf-8 -*-
   2
   3 # Useful doc: https://www.sphinx-doc.org/en/master/extdev/markupapi.html
   4 # Example: https://www.sphinx-doc.org/en/master/development/tutorials/recipe.html
   5
   6 import os
   7 from docutils.parsers.rst import Directive, directives
   8 from docutils import nodes
   9 from docutils.statemachine import StringList
  10 from sphinx.util.osutil import copyfile
  11 from sphinx.util import logging
  12
  13 CSS_FILE = 'showfile.css'
  14 JS_FILE = 'showfile.js'
  15
  16 class ShowFileDirective(Directive):
  17     """
  18     Show a file or propose it to download.
  19     """
  20
  21     has_content = False
  22     optional_arguments = 1
  23     option_spec = {
  24       'language': directives.unchanged
  25     }
  26
  27     def run(self):
  28
  29         filename = self.arguments[0]
  30         language = "python"
  31         if 'language' in self.options:
  32             language = self.options['language']
  33
  34         logger = logging.getLogger(__name__)
  35 #        logger.info('showfile {} in {}'.format(filename, language))
  36
  37         new_content = [
  38           '.. toggle-header::',
  39           '   :header: View {}'.format(filename),
  40           '',
  41           '   `Download {} <https://framagit.org/simgrid/simgrid/tree/{}>`_'.format(os.path.basename(filename), filename),
  42           '',
  43           '   .. literalinclude:: ../../{}'.format(filename),
  44           '      :language: {}'.format(language),
  45           ''
  46         ]
  47
  48         for idx, line in enumerate(new_content):
  49 #            logger.info('{} {}'.format(idx,line))
  50             self.content.data.insert(idx, line)
  51             self.content.items.insert(idx, (None, idx))
  52
  53         node = nodes.container()
  54         self.state.nested_parse(self.content, self.content_offset, node)
  55         return node.children
  56
  57 class ExampleTabDirective(Directive):
  58     """
  59     A group-tab for a given language, in the presentation of the examples.
  60     """
  61     has_content = True
  62     optional_arguments = 0
  63     mandatory_argument = 0
  64
  65     def run(self):
  66         self.assert_has_content()
  67
  68         filename = self.content[0].strip()
  69         self.content.trim_start(1)
  70
  71         (language, langcode) = (None, None)
  72         if filename[-3:] == '.py':
  73             language = 'Python'
  74             langcode = 'py'
  75         elif filename[-4:] == '.cpp':
  76             language = 'C++'
  77             langcode = 'cpp'
  78         elif filename[-4:] == '.xml':
  79             language = 'XML'
  80             langcode = 'xml'
  81         else:
  82             raise Exception("Unknown language '{}'. Please choose '.cpp', '.py' or '.xml'".format(language))
  83
  84         for idx, line in enumerate(self.content.data):
  85             self.content.data[idx] = '   ' + line
  86
  87         for idx, line in enumerate([
  88             '.. group-tab:: {}'.format(language),
  89             '   ']):
  90             self.content.data.insert(idx, line)
  91             self.content.items.insert(idx, (None, idx))
  92
  93         for line in [
  94             '',
  95             '   .. showfile:: {}'.format(filename),
  96             '      :language: {}'.format(langcode),
  97             '']:
  98             idx = len(self.content.data)
  99             self.content.data.insert(idx, line)
 100             self.content.items.insert(idx, (None, idx))
 101
 102 #        logger = logging.getLogger(__name__)
 103 #        logger.info('------------------')
 104 #        for line in self.content.data:
 105 #            logger.info('{}'.format(line))
 106
 107         node = nodes.container()
 108         self.state.nested_parse(self.content, self.content_offset, node)
 109         return node.children
 110
 111 class ToggleDirective(Directive):
 112     has_content = True
 113     option_spec = {'header': directives.unchanged}
 114     optional_arguments = 1
 115
 116     def run(self):
 117         node = nodes.container()
 118         node['classes'].append('toggle-content')
 119
 120         par = nodes.container()
 121         par['classes'].append('toggle-header')
 122         if self.arguments and self.arguments[0]:
 123             par['classes'].append(self.arguments[0])
 124
 125         self.state.nested_parse(StringList([self.options["header"]]), self.content_offset, par)
 126         self.state.nested_parse(self.content, self.content_offset, node)
 127
 128         return [par, node]
 129
 130 def add_assets(app):
 131     app.add_stylesheet(CSS_FILE)
 132     app.add_javascript(JS_FILE)
 133
 134
 135 def copy_assets(app, exception):
 136     if app.builder.name not in ['html', 'readthedocs'] or exception:
 137         return
 138     logger = logging.getLogger(__name__)
 139     logger.info('Copying showfile stylesheet/javascript... ', nonl=True)
 140     dest = os.path.join(app.builder.outdir, '_static', CSS_FILE)
 141     source = os.path.join(os.path.abspath(os.path.dirname(__file__)), CSS_FILE)
 142     copyfile(source, dest)
 143     dest = os.path.join(app.builder.outdir, '_static', JS_FILE)
 144     source = os.path.join(os.path.abspath(os.path.dirname(__file__)), JS_FILE)
 145     copyfile(source, dest)
 146     logger.info('done')
 147
 148 def setup(app):
 149     app.add_directive('toggle-header', ToggleDirective)
 150     app.add_directive('showfile', ShowFileDirective)
 151     app.add_directive('example-tab', ExampleTabDirective)
 152
 153     app.connect('builder-inited', add_assets)
 154     app.connect('build-finished', copy_assets)
 155