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 class ShowFileDirective(Directive):
  14     """
  15     Show a file or propose it to download.
  16     """
  17
  18     has_content = False
  19     optional_arguments = 1
  20     option_spec = {
  21       'language': directives.unchanged
  22     }
  23
  24     def run(self):
  25
  26         filename = self.arguments[0]
  27         language = "python"
  28         if 'language' in self.options:
  29             language = self.options['language']
  30
  31         logger = logging.getLogger(__name__)
  32 #        logger.info('showfile {} in {}'.format(filename, language))
  33
  34         new_content = [
  35           '.. toggle-header::',
  36           '   :header: View {}'.format(filename),
  37           '',
  38           '   `Download {} <https://framagit.org/simgrid/simgrid/tree/{}>`_'.format(os.path.basename(filename), filename),
  39           '',
  40           '   .. literalinclude:: ../../{}'.format(filename),
  41           '      :language: {}'.format(language),
  42           ''
  43         ]
  44
  45         for idx, line in enumerate(new_content):
  46 #            logger.info('{} {}'.format(idx,line))
  47             self.content.data.insert(idx, line)
  48             self.content.items.insert(idx, (None, idx))
  49
  50         node = nodes.container()
  51         self.state.nested_parse(self.content, self.content_offset, node)
  52         return node.children
  53
  54 class ExampleTabDirective(Directive):
  55     """
  56     A group-tab for a given language, in the presentation of the examples.
  57     """
  58     has_content = True
  59     optional_arguments = 0
  60     mandatory_argument = 0
  61
  62     def run(self):
  63         self.assert_has_content()
  64
  65         filename = self.content[0].strip()
  66         self.content.trim_start(1)
  67
  68         (language, langcode) = (None, None)
  69         if filename[-3:] == '.py':
  70             language = 'Python'
  71             langcode = 'py'
  72         elif filename[-4:] == '.cpp':
  73             language = 'C++'
  74             langcode = 'cpp'
  75         elif filename[-4:] == '.xml':
  76             language = 'XML'
  77             langcode = 'xml'
  78         else:
  79             raise Exception("Unknown language '{}'. Please choose '.cpp', '.py' or '.xml'".format(language))
  80
  81         for idx, line in enumerate(self.content.data):
  82             self.content.data[idx] = '   ' + line
  83
  84         for idx, line in enumerate([
  85             '.. group-tab:: {}'.format(language),
  86             '   ']):
  87             self.content.data.insert(idx, line)
  88             self.content.items.insert(idx, (None, idx))
  89
  90         for line in [
  91             '',
  92             '   .. showfile:: {}'.format(filename),
  93             '      :language: {}'.format(langcode),
  94             '']:
  95             idx = len(self.content.data)
  96             self.content.data.insert(idx, line)
  97             self.content.items.insert(idx, (None, idx))
  98
  99 #        logger = logging.getLogger(__name__)
 100 #        logger.info('------------------')
 101 #        for line in self.content.data:
 102 #            logger.info('{}'.format(line))
 103
 104         node = nodes.container()
 105         self.state.nested_parse(self.content, self.content_offset, node)
 106         return node.children
 107
 108 def setup(app):
 109     app.add_directive('showfile', ShowFileDirective)
 110     app.add_directive('example-tab', ExampleTabDirective)
 111