TheLazy.Dev
Portfolio GitHub

Blog

sphinx |markdown |html

Convert Markdown into HTML with Sphinx

unhurried

unhurried

Posted on October 4, 2019

Convert Markdown into HTML with Sphinx

Little notes of a study on a method to convert a markdown file into a HTML file with Sphinx. You can find the deliverable of this study in sphinx-with-markdown.

Enable markdown syntax in Sphinx

Install recommonmark and register it as a markdown parser.

pip install recommonmark
Enter fullscreen mode Exit fullscreen mode

conf.py

source_suffix = ['.rst', '.md']
source_parsers = {
   '.md': 'recommonmark.parser.CommonMarkParser',
}
Enter fullscreen mode Exit fullscreen mode

Activate AutoStructify component that enables the eval_rs syntax to embed reStructuredText in markdown and syntax highlighting by adding the following configuration in conf.py.

from recommonmark.transform import AutoStructify
def setup(app):
    app.add_config_value('recommonmark_config', {
            'auto_toc_tree_section': 'Contents',
            }, True)
    app.add_transform(AutoStructify)
Enter fullscreen mode Exit fullscreen mode

Install sphinx_markdown_tables as recommonmark by itself doesn't support markdown table syntax.

pip install sphinx-markdown-tables
Enter fullscreen mode Exit fullscreen mode

conf.py

extensions = [
    'sphinx_markdown_tables',
]
Enter fullscreen mode Exit fullscreen mode

Internationalization (Multilingualization)

Sphinx has an internationalization feature (sphinx-intl) on top of gettext.

Installation 
pip install sphinx-intl
Enter fullscreen mode Exit fullscreen mode
Usage 
# Compile messages to translate from source code in pot files in {build dir}/gettext.
make gettext
# Generate po files from pot files in {source dir}/locale.
sphinx-intl update -p build/gettext -l en

# Edit the generated po files.

# Specify a language and generate translated documents. 
make -e SPHINXOPTS="-D language='en'" html
Enter fullscreen mode Exit fullscreen mode

When you update the document, you can update po files in the same way.

Edit a PO file

PoEdit is a easy-to-use editor though its complementary version has several feature limitations.

Reference

HTML Themes

Various HTML themes can be found in sphinx-themes.org.

Read the Docs theme seems to be popular among sphinx users.

Docker Image

There are several images in DockerHub which set up sphinx, but none of them seems to be maintained well. Therefore I chose to build my own image from python official image (alpine).

  • hnakamur/sphinx
    • The version of installed sphinx is still 2.0.1 (latest version is 2.1.2.).
  • docker-sphinx-rtd-theme
    • You can use the latest sphinx as its version is not specified in Dockerfile.
    • Python is a little old (3.6), and sphinx-intl is not installed.
  • plaindocs/docker-sphinx
    • Pushed once 4 years ago. Its image size is relatively large as it is based on Ubuntu.

Known Issues

  • The markdown list syntax * item is converted into <li><p>item</p></li>, resulting in generating additional p element and causing styling problems in some HTML templates.
  • Inline styles will be deleted when converting into po files, and they need to be added manually in reST syntax.

Tips

Avoid Warnings on toctree

Sphinx generates a warning when it finds a document which is not included in any toctree.

checking consistency... C:\Users\xxx\Desktop\sx\source\test.md: WARNING: document isn't included in any toctree
Enter fullscreen mode Exit fullscreen mode

To suppress the warning, add orphan in the first line of the document.

Other Useful Packages

  • Export documents in ePub format: pip install Pillow
  • Watch changes on documents and re-build automatically: pip install sphinx-autobuild

Reference

💖 💪 🙅 🚩
unhurried
unhurried

Posted on October 4, 2019

Join Our Newsletter. No Spam, Only the good stuff.

Sign up to receive the latest update from our blog.

Related

Convert Markdown into HTML with Sphinx
sphinx Convert Markdown into HTML with Sphinx

October 4, 2019