-
Notifications
You must be signed in to change notification settings - Fork 2
/
include.rst
106 lines (80 loc) · 2.76 KB
/
include.rst
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
##################
Includes
##################
The include DocDown tag allows for including code samples as well as CSV files into the markdown from separate files
to allow for easier maintaining and multiple inclusions. CSV files are rendered as HTML tables, otherwise files are displayed as code blocks.
Files will be looked for initially under ``current_directory/asset_directory/``. If not found, one directory will
be removed from ``current_directory`` until ``current_directory`` is the same as ``root_directory``.
=============
Dependencies
=============
The ``docdown.include`` extension requires `markdown.extensions.fenced_code`_ to be used as well.
==============
Configuration
==============
root_directory
Base directory where source code files to include can be found. The extension will not look above this
directory for source code includes.
current_directory
The lowest level nested directory to start searching for source code includes in. The extension will start
here and roll up until ``root_directory``
asset_directory
A directory within ``current_directory`` where the source code includes exist.
----------
Example
----------
* /mnt/media/
* assets/
* c/assets/
* c/headers/assets/
A configuration where ``root_directory`` is ``/mnt/media/``, ``current_directory`` is ``/mnt/media/c/headers/``,
and ``asset_directory`` is ``assets`` would start looking for a file in ``/mnt/media/c/headres/assets/``. If it is
not found then the next directory checked would be ``/mnt/media/c/assets/``, and then ``/mnt/media/assets/``
=======
Usage
=======
In documents
-------------
.. code-block:: html
+++ test.cpp
Python
--------------
.. code-block:: python
_root = os.path.dirname(os.path.abspath(__file__))
root_directory = os.path.join('/', 'projects', 'src')
current_directory = os.path.join(_root, 'test_files', 'nested', 'path')
config = {
'docdown.include': {
'asset_directory': asset_dir,
'root_directory': current_directory,
'current_directory':
'extension_map': {
'.m': '.c',
}
}
}
text = '+++ test.json'
html = markdown.markdown(
text,
extensions= [
'markdown.extensions.fenced_code',
'docdown.include'],
extension_configs=config,
output_format='html5')
=======
Output
=======
Where test.json contains
.. code-block:: json
{
"test": "json",
"asdf": true
}
HTML output will be
.. code-block:: html
<p>Test JSON:</p>
<pre><code class="json">
"test":
"content"}
</code></pre>
.. _`markdown.extensions.fenced_code`: https://pythonhosted.org/Markdown/extensions/fenced_code_blocks.html