Skip to content

Commit 858891b

Browse files
jemerickjemerick
authored
Merge pull request #16 from livio/platform-sections
Add Platform Sections DocDown Extension
2 parents 26e7727 + aad8b17 commit 858891b

10 files changed

Lines changed: 315 additions & 20 deletions

File tree

‎.travis.yml‎

Lines changed: 9 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,15 @@
11
# Config file for automatic testing at travis-ci.org
22
# This file will be regenerated if you run travis_pypi_setup.py
33
# test to trigger commit
4-
4+
dist: xenial # required for Python >= 3.7
55
language: python
6-
python: 3.5
7-
8-
env:
9-
- TOXENV=py35
10-
- TOXENV=py34
11-
- TOXENV=py33
12-
- TOXENV=py27
13-
- TOXENV=pypy
14-
- TOXENV=coverage
6+
python:
7+
- "2.7"
8+
- "3.4"
9+
- "3.5"
10+
- "3.6"
11+
- "3.7"
1512

16-
# command to install dependencies, e.g. pip install -r requirements.txt --use-mirrors
17-
install: pip install -U tox
13+
install: pip install -r requirements_dev.txt
1814

19-
# command to run tests, e.g. python setup.py test
20-
script: tox -e ${TOXENV}
15+
script: python setup.py test

‎HISTORY.rst‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,13 @@
22
History
33
=======
44

5-
0.1.1 (2016-12-16)
5+
0.2.0 (2019-05-29)
6+
__________
7+
8+
* Add Platform Section Markdown Extension
9+
10+
11+
0.1.2 (2016-12-16)
612
__________
713

814
* Strip leading ./ from media urls when concatenating with a set media_url

‎docdown/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,4 @@
22

33
__author__ = """Jason Emerick"""
44
__email__ = 'jason@mobelux.com'
5-
__version__ = '0.1.2'
5+
__version__ = '0.2.0'

‎docdown/platform_section.py‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# -*- coding: utf-8 -*-
2+
3+
"""
4+
platform_section
5+
----------------------------------
6+
7+
docdown.platform_section Markdown extension module
8+
"""
9+
10+
from __future__ import absolute_import, print_function, unicode_literals
11+
12+
import re
13+
14+
from markdown.extensions import Extension
15+
from markdown.preprocessors import Preprocessor
16+
17+
18+
class PlatformSectionPreprocessor(Preprocessor):
19+
20+
RE = re.compile(r'''
21+
^@!\[(?P<sections>[\w,]+)\]\W*\n
22+
(?P<content>.*?)(?<=\n)
23+
\W*!@\W*$''', re.MULTILINE | re.DOTALL | re.VERBOSE)
24+
25+
def __init__(self, platform_section, **kwargs):
26+
self.platform_section = platform_section.lower().strip()
27+
super(PlatformSectionPreprocessor, self).__init__(**kwargs)
28+
29+
def run(self, lines):
30+
text = "\n".join(lines)
31+
while 1:
32+
m = self.RE.search(text)
33+
if m:
34+
sections = [section.lower().strip() for section in m.group('sections').split(',')]
35+
36+
content = m.group('content')
37+
38+
if self.platform_section in sections:
39+
text = '%s\n%s\n%s' % (text[:m.start()], content, text[m.end():])
40+
else:
41+
text = '%s\n%s' % (text[:m.start()], text[m.end():])
42+
else:
43+
break
44+
45+
return text.split("\n")
46+
47+
48+
class PlatformSectionExtension(Extension):
49+
"""
50+
Renders a block of content if and only if the configured platform section is in the DocDown tag's list of platform
51+
sections.
52+
53+
Configuration Example:
54+
{
55+
'platform_section': 'Android',
56+
}
57+
"""
58+
59+
def __init__(self, **kwargs):
60+
self.config = {
61+
'platform_section': ['', 'The platform section that should be rendered.'],
62+
}
63+
super(PlatformSectionExtension, self).__init__(**kwargs)
64+
65+
def extendMarkdown(self, md, md_globals):
66+
""" Add NoteBlockPreprocessor to the Markdown instance. """
67+
md.registerExtension(self)
68+
69+
platform_section = self.getConfig('platform_section')
70+
71+
md.preprocessors.add('platform_sections',
72+
PlatformSectionPreprocessor(
73+
platform_section=platform_section,
74+
markdown_instance=md),
75+
">normalize_whitespace")
76+
77+
78+
def makeExtension(*args, **kwargs):
79+
return PlatformSectionExtension(*args, **kwargs)

‎docs/docdown.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,14 @@ docdown.note_blocks module
5151
:undoc-members:
5252
:show-inheritance:
5353

54+
docdown.platform_section module
55+
-------------------------------
56+
57+
.. automodule:: docdown.platform_section
58+
:members:
59+
:undoc-members:
60+
:show-inheritance:
61+
5462
docdown.sequence module
5563
-----------------------
5664

‎docs/extensions/platform_sections.rst‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
######################
2+
Platform Sections
3+
######################
4+
5+
Platform Sections allows for showing or hiding content sections based on which platform the documentation is being built for.
6+
7+
A platform section is delimited by ``@![platform,section]`` and ``!@``. Section names are case insensitive and multiple
8+
platform sections can be comma separated in the tag as shown above.
9+
10+
The configuration for the platform section is just ``platform_section`` as shown below. This is the section that will be
11+
shown for that build and other sections will be hidden.
12+
13+
==============
14+
Configuration
15+
==============
16+
17+
``platform_section``
18+
Case insensitive name of section to show. All other sections will be hidden.
19+
20+
=======
21+
Usage
22+
=======
23+
In documents
24+
-------------
25+
26+
.. code-block:: html
27+
28+
@![Android]
29+
This section will be shown for the Android build
30+
!@
31+
32+
@![iOS]
33+
This section will be displayed for the iOs build.
34+
!@
35+
36+
@![JavaSE,JavaEE]
37+
This section will be displayed for Java SE and EE builds.
38+
!@
39+
40+
Python
41+
--------------
42+
43+
.. code-block:: python
44+
45+
config = {
46+
'docdown.platform_section': {
47+
'platform_section': 'Android',
48+
},
49+
}
50+
51+
text = ('@![iOS]\n'
52+
'some iOS content not shown\n\n'
53+
'!@\n'
54+
'\n'
55+
'@![Android]\n'
56+
'some Android content shown\n\n'
57+
'!@\n')
58+
59+
html = markdown.markdown(
60+
text,
61+
extensions=['docdown.platform_section'],
62+
extension_configs=config,
63+
output_format='html5')
64+
65+
=======
66+
Output
67+
=======
68+
69+
.. code-block:: html
70+
71+
<p>some Android content shown</p>

‎setup.cfg‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
[bumpversion]
2-
current_version = 0.1.2
2+
current_version = 0.2.0
33
commit = True
44
tag = True
55

@@ -17,4 +17,3 @@ universal = 1
1717
[flake8]
1818
exclude = docs,docdown/template_adapters/__init__.py
1919
max-line-length = 120
20-

‎setup.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020

2121
setup(
2222
name='docdown',
23-
version='0.1.2',
23+
version='0.2.0',
2424
description="DocDown is a Markdown extension for source code documentation.",
2525
long_description=readme + '\n\n' + history,
2626
author="Jason Emerick, Justin Michalicek",

‎tests/test_platform_section_extension.py‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# -*- coding: utf-8 -*-
2+
3+
"""
4+
test_note_blocks_extension
5+
----------------------------------
6+
7+
Tests for `docdown.note_blocks` module.
8+
"""
9+
10+
from __future__ import absolute_import, print_function, unicode_literals
11+
12+
import unittest
13+
14+
import markdown
15+
16+
17+
class PlatformSectionExtensionTest(unittest.TestCase):
18+
"""
19+
Integration test with markdown for :class:`docdown.platform_section.PlatformSectionExtension`
20+
"""
21+
MARKDOWN_EXTENSIONS = ['docdown.platform_section']
22+
23+
def build_config_for_platform_section(self, section):
24+
return {
25+
'docdown.platform_section': {
26+
'platform_section': section,
27+
}
28+
}
29+
30+
def test_section_does_not_match(self):
31+
text = ('@![asdf]\n'
32+
'some content\nnot shown\n\n'
33+
'!@')
34+
35+
html = markdown.markdown(
36+
text,
37+
extension_configs=self.build_config_for_platform_section('Android'),
38+
extensions=self.MARKDOWN_EXTENSIONS,
39+
output_format='html5'
40+
)
41+
expected_output = ''
42+
self.assertEqual(expected_output, html)
43+
44+
def test_section_does_match(self):
45+
text = ('@![asdf]\n'
46+
'some content\nshown\n\n'
47+
'!@ \n')
48+
49+
html = markdown.markdown(
50+
text,
51+
extension_configs=self.build_config_for_platform_section('asdf'),
52+
extensions=self.MARKDOWN_EXTENSIONS,
53+
output_format='html5'
54+
)
55+
expected_output = '<p>some content\nshown</p>'
56+
self.assertEqual(expected_output, html)
57+
58+
def test_section_markdown_case_insensitive(self):
59+
text = ('@![ASDF]\n'
60+
'some content\nshown\n\n'
61+
'!@\n')
62+
63+
html = markdown.markdown(
64+
text,
65+
extension_configs=self.build_config_for_platform_section('asdf'),
66+
extensions=self.MARKDOWN_EXTENSIONS,
67+
output_format='html5'
68+
)
69+
expected_output = '<p>some content\nshown</p>'
70+
self.assertEqual(expected_output, html)
71+
72+
def test_section_config_case_insensitive(self):
73+
text = ('@![asdf]\n'
74+
'some content\nshown\n\n'
75+
'!@ \n')
76+
77+
html = markdown.markdown(
78+
text,
79+
extension_configs=self.build_config_for_platform_section('ASDF'),
80+
extensions=self.MARKDOWN_EXTENSIONS,
81+
output_format='html5'
82+
)
83+
expected_output = '<p>some content\nshown</p>'
84+
self.assertEqual(expected_output, html)
85+
86+
def test_multiple_platforms_section(self):
87+
text = ('@![asdf,QwErTy]\n'
88+
'some content\nshown\n\n'
89+
'!@\n')
90+
91+
html = markdown.markdown(
92+
text,
93+
extension_configs=self.build_config_for_platform_section('qwerty'),
94+
extensions=self.MARKDOWN_EXTENSIONS,
95+
output_format='html5'
96+
)
97+
expected_output = '<p>some content\nshown</p>'
98+
self.assertEqual(expected_output, html)
99+
100+
def test_multiple_sections(self):
101+
text = ('@![asdf,QwErTy]\n'
102+
'some content\nnot shown\n\n'
103+
'!@\n'
104+
'\n'
105+
'@![zxcv]\n'
106+
'some content\nshown\n\n'
107+
'!@\n')
108+
109+
html = markdown.markdown(
110+
text,
111+
extension_configs=self.build_config_for_platform_section('zxcv'),
112+
extensions=self.MARKDOWN_EXTENSIONS,
113+
output_format='html5'
114+
)
115+
expected_output = '<p>some content\nshown</p>'
116+
self.assertEqual(expected_output, html)
117+
118+
def test_multiple_sections_with_code_snippet(self):
119+
text = ('@![iOS]\n'
120+
'some iOS content not shown\n\n'
121+
'!@\n'
122+
'\n'
123+
'@![Android]\n'
124+
'some Android content shown\n\n'
125+
'``` java\n'
126+
'String java = "asdf";\n'
127+
'```\n'
128+
'!@\n')
129+
130+
html = markdown.markdown(
131+
text,
132+
extension_configs=self.build_config_for_platform_section('Android'),
133+
extensions=self.MARKDOWN_EXTENSIONS,
134+
output_format='html5'
135+
)
136+
expected_output = '<p>some Android content shown</p>\n<p>``` java\nString java = "asdf";</p>'
137+
self.assertEqual(expected_output, html)

‎tox.ini‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
[tox]
2-
envlist = py27, py33, py34, py35, flake8, coverage
2+
envlist = py27, py34, py35, py36, py37, flake8, coverage
33

44
[testenv:coverage]
55
deps =

0 commit comments

Comments
 (0)