3 from docutils
import nodes, io, utils
4 from docutils.parsers
import rst
5 from docutils.core
import ErrorString
6 from docutils.utils
import SafeString
8 from recommonmark.parser
import CommonMarkParser
12 """Directive class to include markdown in sphinx. 13 Load a file and convert it to rst and insert as a node. Currently 14 directive-specific options are not implemented. 15 See https://github.com/sphinx-doc/sphinx/issues/7000 16 and https://github.com/readthedocs/recommonmark/issues/191 18 required_arguments = 1
19 optional_arguments = 0
26 """Most of this method is from ``docutils.parser.rst.Directive``. 27 docutils version: 0.12 29 if not self.state.document.settings.file_insertion_enabled:
30 raise self.warning(
'"%s" directive disabled.' % self.name)
31 source = self.state_machine.input_lines.source(
32 self.lineno - self.state_machine.input_offset - 1)
33 source_dir = os.path.dirname(os.path.abspath(source))
34 path = rst.directives.path(self.arguments[0])
35 path = os.path.normpath(os.path.join(source_dir, path))
36 path = utils.relative_path(
None, path)
37 path = nodes.reprunicode(path)
40 encoding = self.options.get(
41 'encoding', self.state.document.settings.input_encoding)
42 e_handler = self.state.document.settings.input_encoding_error_handler
46 self.state.document.settings.record_dependencies.add(path)
47 include_file = io.FileInput(source_path=path,
49 error_handler=e_handler)
50 except UnicodeEncodeError:
51 raise self.severe(
'Problems with "%s" directive path:\n' 52 'Cannot encode input file path "%s" ' 54 (self.name, SafeString(path)))
55 except OSError
as error:
56 raise self.severe(
'Problems with "%s" directive path:\n%s.' %
57 (self.name, ErrorString(error)))
60 startline = self.options.get(
'start-line',
None)
61 endline = self.options.get(
'end-line',
None)
63 if startline
or (endline
is not None):
64 lines = include_file.readlines()
65 rawtext =
''.join(lines[startline:endline])
67 rawtext = include_file.read()
68 except UnicodeError
as error:
69 raise self.severe(
'Problem with "%s" directive:\n%s' %
70 (self.name, ErrorString(error)))
72 class CustomCommonMarkParser(CommonMarkParser):
73 """Temporary workaround to remove multiple build warnings caused by upstream bug. 74 See https://github.com/readthedocs/recommonmark/issues/177 for details. 77 def visit_document(self, node):
80 doc = utils.new_document(self.arguments[0])
81 md_parser = CustomCommonMarkParser()
82 md_parser.parse(rawtext, doc)
83 return [*doc.children]
87 app.add_directive(
"mdinclude", MdInclude)
91 'parallel_read_safe':
True,
92 'parallel_write_safe':
True,