Convert Markdown into HTML with Sphinx
Tags: sphinx, markdown, html
Published: 2019-10-04 09:42:05

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](https://github.com/unhurried/sphinx-with-markdown).

#### Enable markdown syntax in Sphinx

Install [recommonmark](https://recommonmark.readthedocs.io/en/stable/) and register it as a markdown parser.


```shell
pip install recommonmark
```

conf.py

```python
source_suffix = ['.rst', '.md']
source_parsers = {
   '.md': 'recommonmark.parser.CommonMarkParser',
}
```

Activate [AutoStructify](https://recommonmark.readthedocs.io/en/latest/auto_structify.html) component that enables the `eval_rs` syntax to embed reStructuredText in markdown and syntax highlighting by adding the following configuration in conf.py.

```python
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](https://github.com/ryanfox/sphinx-markdown-tables) as recommonmark by itself doesn't support markdown table syntax.

```shell
pip install sphinx-markdown-tables
```

conf.py

```python
extensions = [
    'sphinx_markdown_tables',
]
```

#### Internationalization (Multilingualization)

Sphinx has an internationalization feature ([sphinx-intl](http://www.sphinx-doc.org/ja/stable/intl.html)) on top of gettext.

##### Installation

```shell
pip install sphinx-intl
```

##### Usage

```shell
# 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](https://poedit.net/) is a easy-to-use editor though its complementary version has several feature limitations.

##### Reference

* https://conyac.cc/ja/business/columns/localization_guide_po_pot

#### HTML Themes

Various HTML themes can be found in [sphinx-themes.org](https://sphinx-themes.org/).

[Read the Docs](https://sphinx-rtd-theme.readthedocs.io/en/stable/) 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](https://hub.docker.com/r/hnakamur/sphinx/)
  - The version of installed sphinx is still 2.0.1 (latest version is 2.1.2.).
- [docker-sphinx-rtd-theme](https://hub.docker.com/r/suttang/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](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
```

To suppress the warning, add [orphan](https://sphinx-users.jp/reverse-dict/system/orphan.html) 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

- [Official Documentation](http://www.sphinx-doc.org/ja/stable/contents.html)
- https://qiita.com/pashango2/items/d1b379b699af85b529ce