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
conf.py
source_suffix = ['.rst', '.md']
source_parsers = {
'.md': 'recommonmark.parser.CommonMarkParser',
}
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)
Install sphinx_markdown_tables as recommonmark by itself doesn't support markdown table syntax.
pip install sphinx-markdown-tables
conf.py
extensions = [
'sphinx_markdown_tables',
]
Internationalization (Multilingualization)
Sphinx has an internationalization feature (sphinx-intl) on top of gettext.
Installation
pip install sphinx-intl
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
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
* itemis 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
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
Top comments (1)
convert markdown to html online is also a good choice