Welcome to Python DocDown’s documentation!¶
Contents:
Python DocDown¶
Python DocDown is a suite of extensions for Python Markdown.
Documentation¶
Run make docs to build the HTML documentation for Python DocDown
Credits¶
This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.
Installation¶
Stable release¶
To install Python DocDown, run this command in your terminal:
$ pip install docdown
This is the preferred method to install Python DocDown, as it will always install the most recent stable release.
If you don’t have pip installed, this Python installation guide can guide you through the process.
From sources¶
The sources for Python DocDown can be downloaded from the Github repo.
You can either clone the public repository:
$ git clone git://github.com/livio/DocDown-Python
Or download the tarball:
$ curl -OL https://github.com/livio/DocDown-Python/tarball/master
Once you have a copy of the source, you can install it with:
$ python setup.py install
Extensions¶
Extensions to the Markdown package provided by DocDown
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_directorywhere 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¶
+++ test.cpp
_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
{
"test": "json",
"asdf": true
}
HTML output will be
<p>Test JSON:</p>
<pre><code class="json">
"test":
"content"}
</code></pre>
Links¶
The Links DocDown extension allow for custom, pre-generated links to be reference from normal markdown link syntax. Via the configuration, a link map can be included which provides a dictionary of names to URLs. All the links are checked against this dictionary and if found in the dictionary, the URL provided in the dictionary replaces the URL in the markdown.
Usage¶
In documents¶
[this is a link](http://mobelux.com/)
[this is a link](to/nowhere)
[this is a link](to/nowhere#testhash)
Python¶
config = {
'docdown.links': {
'link_map': {
'to/nowhere': 'home/localhost',
},
}
}
text = ('[this is a link](http://mobelux.com/)\n'
'[this is a link](to/nowhere)\n'
'[this is a link](to/nowhere@testhash)')
html = markdown.markdown(
text,
extensions=['docdown.links'],
extension_configs=config,
output_format='html5')
Output¶
<p><a href="http://mobelux.com/">this is a link</a></p>
<p><a href="home/localhost">this is a link</a></p>
<p><a href="home/localhost#testhash">this is a link</a></p>
Media¶
The media DocDown extension updates all images that do not start with http or // to use the configurable media URL.
Usage¶
HTML¶
Python¶
config = {
'docdown.media': {
'media_url': 'https://example.com/media/'
}
}
text = ('\n'
'\n'
'![Alt Text(./assets/image.png)\n')
html = markdown.markdown(
text,
extensions=['docdown.media'],
extension_configs=config,
output_format='html5'
)
Output¶
<p><img src="http://example.com/static/img/image.png" alt="Alt Text"></p>
<p><img src="https://example.com/media/assets/image.png" alt="Alt Text"></p>
<p><img src="https://example.com/media/assets/image.png" alt="Alt Text"></p>
Note Blocks¶
Note blocks allows for calling out content in note like fashion. The note type context is configurable through the options passed to the markdown extension.
A note block is delimited by three exclamation points. The beginning exclamation point also includes the note type.
The configuration for the notes has a prefix and postfix template strings which can be templated using
any of the provided Template Adapters template renderers or with a custom renderer. The default
renderer uses standard Python str.format() substitutions for templating.
Configuration¶
- prefix
- String which prefix the note block text. This can be templated using any of the provided Template Adapters template renderers or with a custom renderer.
- postfix
- String which will be appended to the note block text. This can be templated using any of the provided Template Adapters template renderers or with a custom renderer.
- tags
- A dict of tag names which are also dicts of configuration. The keys and values will be used as template
context for the prefix and postfix templates. The tag key will additionally be added to this with a key of
tag. - default_tag
- The name of a tag to use as the default if the markdown string specifies one which is not configured in the tags dict.
Usage¶
In documents¶
!!! MUST
hello world!
!!!
!!! MAY
I have a custom prefix and postfix
!!!
!!! DEFAULT
I will look like MUST was specified
!!!'
Python¶
config = {
'docdown.note_blocks': {
'prefix': ('<div class="{tag}">\n<div class="icon">\n{{% svg "{svg}" %}}'
'<img class="icon--pdf" src="{{% static "{svg_path}" %}}">\n</div>\n<h5>{title}</h5>'),
'postfix': '</div>',
'default_tag': 'must',
'tags': {
'must': {
'svg': 'standard/icon-must',
'svg_path': 'svg/standard/icon-must.svg',
'title': 'Must',
},
'may': {
'svg': 'standard/icon-may',
'svg_path': 'svg/standard/icon-may.svg',
'title': 'May',
'prefix': ('<div class="custom-prefix {tag}">\n<div class="icon">\n{{% svg "{svg}" %}}'
'<img class="icon--pdf" src="{{% static "{svg_path}" %}}">\n</div>\n<h5>{title}</h5>'),
'postfix': '<span>Custom Postfix</span></div>',
},
},
},
}
text = ('!!! MUST\n'
'hello world\n'
'!!!\n\n'
'!!! MAY\n'
'I have a custom prefix and postfix\n'
'!!!\n\n'
'!!! DEFAULT\n'
'I will look like MUST was specified\n'
'!!!')
html = markdown.markdown(
text,
extensions=['docdown.note_blocks'],
extension_configs=config,
output_format='html5')
Output¶
<div class="must">
<div class="icon">
{% svg "standard/icon-must" %}<img class="icon--pdf" src="{% static "svg/standard/icon-must.svg" %}">
</div>
<h5>Must</h5>
<p>hello world</p>
</div>
<div class="custom-prefix may">
<div class="icon">
{% svg "standard/icon-may" %}<img class="icon--pdf" src="{% static "svg/standard/icon-may.svg" %}">
</div>
<h5>May</h5>
<p>I have a custom prefix and postfix</p>
<span>Custom Postfix</span></div>
<div class="must">
<div class="icon">
{% svg "standard/icon-must" %}<img class="icon--pdf" src="{% static "svg/standard/icon-must.svg" %}">
</div>
<h5>Must</h5>
<p>I will look like MUST was specified</p>
</div>
Platform Sections¶
Platform Sections allows for showing or hiding content sections based on which platform the documentation is being built for.
A platform section is delimited by @![platform,section] and !@. Section names are case insensitive and multiple
platform sections can be comma separated in the tag as shown above.
The configuration for the platform section is just platform_section as shown below. This is the section that will be
shown for that build and other sections will be hidden.
Configuration¶
platform_section- Case insensitive name of section to show. All other sections will be hidden.
Usage¶
In documents¶
@![Android]
This section will be shown for the Android build
!@
@![iOS]
This section will be displayed for the iOs build.
!@
@![JavaSE,JavaEE]
This section will be displayed for Java SE and EE builds.
!@
Python¶
config = {
'docdown.platform_section': {
'platform_section': 'Android',
},
}
text = ('@![iOS]\n'
'some iOS content not shown\n\n'
'!@\n'
'\n'
'@![Android]\n'
'some Android content shown\n\n'
'!@\n')
html = markdown.markdown(
text,
extensions=['docdown.platform_section'],
extension_configs=config,
output_format='html5')
Output¶
<p>some Android content shown</p>
Sequence Diagrams¶
Sequence diagrams allow for including diagram images that can be opened to be be separately vs be included directly in the HTML as a standard image.
A sequence diagram is bracketed by three pipes ||| and the last line of the block should be a markdown image tag. The alt title of this image can be left blank to default to Sequence Diagram, otherwise this will be used as the title for the sequence diagram block.
The configuration for the sequence diagrams has a prefix and postfix template strings which can be templated using
any of the provided Template Adapters template renderers or with a custom renderer. The default renderer
uses standard Python str.format() substitutions for templating.
The context will include image_url and title which come from the markdown image tag. The markdown image tag is not rendered, only the content within the tag. The image url is also updated to include the media url from the configuration.
Usage¶
HTML¶
|||
Activate App
|||
Python¶
config = {
'docdown.sequence': {
'media_url': 'https://example.com/media/',
'prefix': ('<div class="visual-link-wrapper">\n'
'<a href="#" data-src="{{{ image_url }}}" class="visual-link">\n'
'<div class="visual-link__body">\n<div class="t-h6 visual-link__title">{{ title }}</div>\n'
'<p class="t-default">\n'),
'postfix': ('</p></div><div class="visual-link__link fx-wrapper fx-s-between fx-a-center">\n'
'<span class="fc-theme">View Diagram</span>\n'
'<span class="icon">{% svg "standard/icon-visual" %}</span>\n'
'</div>\n</a>\n</div>\n<img class="visual-print-image" src="{{{ image_url }}}">'),
}
}
text = ('# Sequence Diagrams\n'
'|||\n'
'Activate App\n'
'\n'
'|||')
html = markdown.markdown(
text,
extensions=['docdown.sequence'],
extension_configs=config,
output_format='html5')
Output¶
<div class="visual-link-wrapper">
<a href="#" data-src="https://example.com/media/assets/ActivateApp.png" class="visual-link">
<div class="visual-link__body">
<div class="t-h6 visual-link__title">Activate App Sequence Diagram</div>
<p class="t-default">
<p>Activate App</p>
</p>
</div>
<div class="visual-link__link fx-wrapper fx-s-between fx-a-center">
<span class="fc-theme">View Diagram</span>
<span class="icon">{% svg "standard/icon-visual" %}</span>
</div>
</a>
</div>
<img class="visual-print-image" src="https://smartdevicelink.com/media/assets/ActivateApp.png">
Template Adapters¶
Some DocDown extensions make use of blocks of HTML which the user may configure via templates. Python DocDown
uses template adapter classes which provide a render(template, context) method to allow for a configurable
templating language to be used. The templatable extensions have a template_adapter configuration paramters which
takes the module and class to use, such as docdown.template_adapters.StringFormatAdapter.
The following template adapters are provided by the Python DocDown package.
docdown.template_adapters.StringFormatAdapters- This is the default adapter. It uses standard Python string formatting for the templates.
docdown.template_adapters.TemplateStringAdapterTemplateStringAdapteruses Python template strings for the HTML template.
Contributing¶
Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
You can contribute in many ways:
Types of Contributions¶
Report Bugs¶
Report bugs at https://github.com/livio/DocDown-Python/issues.
If you are reporting a bug, please include:
- Your operating system name and version.
- Any details about your local setup that might be helpful in troubleshooting.
- Detailed steps to reproduce the bug.
Fix Bugs¶
Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.
Implement Features¶
Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.
Write Documentation¶
Python DocDown could always use more documentation, whether as part of the official Python DocDown docs, in docstrings, or even on the web in blog posts, articles, and such.
Submit Feedback¶
The best way to send feedback is to file an issue at https://github.com/livio/DocDown-Python/issues.
If you are proposing a feature:
- Explain in detail how it would work.
- Keep the scope as narrow as possible, to make it easier to implement.
- Remember that this is a volunteer-driven project, and that contributions are welcome :)
Get Started!¶
Ready to contribute? Here’s how to set up docdown for local development.
Fork the docdown repo on GitHub.
Clone your fork locally:
$ git clone git@github.com:your_name_here/DocDown-Python.git docdown_python
Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:
$ mkvirtualenv docdown_python $ cd docdown_python/ $ python setup.py developCreate a branch for local development:
$ git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:
$ flake8 docdown tests $ python setup.py test or py.test $ toxTo get flake8 and tox, just pip install them into your virtualenv.
Commit your changes and push your branch to GitHub:
$ git add . $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-featureSubmit a pull request through the GitHub website.
Pull Request Guidelines¶
Before you submit a pull request, check that it meets these guidelines:
- The pull request should include tests.
- If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
- The pull request should work for Python 2.7, 3.2, 3.3, 3.4 and 3.5, and for PyPy. Check https://travis-ci.org/livio/DocDown-Python/pull_requests and make sure that the tests pass for all supported Python versions.