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 = {
 114         'header': directives.unchanged,
 115         'show': directives.flag
 116     }
 117     optional_arguments = 1
 118
 119     def run(self):
 120         node = nodes.container()
 121         node['classes'].append('toggle-content')
 122         if "show" not in self.options:
 123             # This :show: thing is not working, and I fail to see why.
 124             # Only the hidden-content class gets a call to hide() in the Javascript,
 125             # and :show:n block# still get hidden when I load the page.
 126             # No idea what's going on (Mt)
 127             node['classes'].append('hidden-content')
 128
 129         par = nodes.container()
 130         par['classes'].append('toggle-header')
 131         if self.arguments and self.arguments[0]:
 132             par['classes'].append(self.arguments[0])
 133
 134         self.state.nested_parse(StringList([self.options["header"]]), self.content_offset, par)
 135         self.state.nested_parse(self.content, self.content_offset, node)
 136
 137         return [par, node]
 138
 139 def add_assets(app):
 140     app.add_stylesheet(CSS_FILE)
 141     app.add_javascript(JS_FILE)
 142
 143
 144 def copy_assets(app, exception):
 145     if app.builder.name not in ['html', 'readthedocs'] or exception:
 146         return
 147     logger = logging.getLogger(__name__)
 148     logger.info('Copying showfile stylesheet/javascript... ', nonl=True)
 149     dest = os.path.join(app.builder.outdir, '_static', CSS_FILE)
 150     source = os.path.join(os.path.abspath(os.path.dirname(__file__)), CSS_FILE)
 151     copyfile(source, dest)
 152     dest = os.path.join(app.builder.outdir, '_static', JS_FILE)
 153     source = os.path.join(os.path.abspath(os.path.dirname(__file__)), JS_FILE)
 154     copyfile(source, dest)
 155     logger.info('done')
 156
 157 def setup(app):
 158     app.add_directive('toggle-header', ToggleDirective)
 159     app.add_directive('showfile', ShowFileDirective)
 160     app.add_directive('example-tab', ExampleTabDirective)
 161
 162     app.connect('builder-inited', add_assets)
 163     app.connect('build-finished', copy_assets)
 164