[PYTHON] Sphinx extension to arbitrarily convert text in pre-processing of document generation

Premise

Recently, I am writing a document with Sphinx.

• I want to write with markdown from restructuredText
• According to the official document, commonMark can be used, but Table cannot be used.
• "A good library!" ← [Introduction of M2R that can mix Markdown and reStructuredText in a single file (Sphinx extension compatible)](http://h-miyako.hatenablog.com/entry/2017/08/ 11/133620)

So I solved it once, but when using PlantUML, it became stressful that I could not preview on VS Code.

Thing you want to do

When making html

```plantuml

Enclose

.. uml::

I want to automatically convert to.

#policy

Official documentationThere is an event implementation method inside.

• 「Sphinx.connect(event, callback)It seems that the callback function for the event is specified with. -Various event definitions are "Sphinx core eventsThere is. -If you want to convert plain text like this time,source-read(app, docname, source)Can be used.

#Extension plugin implementation

I wrote it like this.

uml_change.py

def uml_change(app, docname, source):  
    umlFlg = False
    lines = []
    for line in source[0].split("\n"):
        if umlFlg:
            if line.strip() == "```":
                #Delete when the end of the box comes
                line = ""
                umlFlg = False
            else:
                #Indent inside the box
                line = "    " + line

        ###Convert markdown notation to reST notation
        if line.strip() == "```plantuml":
            line = ".. uml::"
            umlFlg = True
           
        lines.append(line)

    source[0] = "\n".join(lines)
  
def setup(app):  
    app.connect("source-read", uml_change)  

conf.py settings

conf.Add the following description to py.

conf.py

import sys
import os
 sys.path.append (os.path.abspath ("./ bin")) # Folder name is an example

Store the above script in the specified folder (under bin in the above example).

Add the created plugin name to extensions.

conf.py

extensions = ['uml_change']

Try make html and if the uml image is displayed, it succeeds.

#Supplement

You should be able to write various preprocessing by applying this method. Convert markdown link format to restructuredText format, etc.