Sphinx Recommonmark CommonMarkParser 未检测到 URL 链接

Question

我正在使用 Sphinx 从 Markdown 文件中构建文档。 文档很清楚 myst-parser 应该以典型的[some text](www.example.com) 方式处理降价链接。

随后我安装了myst-parser，设置扩展名extensions = ['myst_parser']并指定source_suffix：

source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'markdown',
    '.md': 'markdown',
}

不幸的是，链接没有正确转换，只是显示为以下 HTML：

[some text](<a class="reference external" href="www.example.com">www.example.com</a>)

然后在浏览器中以以下方式显示[some text](www.example.com)，这显然不是预期的链接。

我也尝试通过以下方式使用 Recommonmark：

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

source_suffix = ['.rst', '.md']

正如 here 和 here 所解释的，但最终得到了相同的输出。 如何解决这个相当简单的问题？

正在使用的版本： 推荐 0.7.1 神秘解析器 0.13.6 狮身人面像 3.5.4 蟒蛇3.9.2

编辑 在这里找到更新的 conf.py 文件

# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------
import sphinx_rtd_theme
import sys
import os

print("CURRENT WORKING DIRECTORY")
print(os.getcwd())
print('adding path')
sys.path.insert(0, r'path_to_repo')
print(sys.path)

# At top on conf.py (with other import statements)
import recommonmark
from recommonmark.transform import AutoStructify
from recommonmark.parser import CommonMarkParser

# -- Project information -----------------------------------------------------
project = 'py_neuromodulation'
copyright = '2021, John Doe'
author = 'John Doe'

source_parsers = {
    '.md': 'recommonmark.parser.CommonMarkParser',
}
source_suffix = ['.rst', '.md']
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary',
    'sphinx.ext.doctest',
    'sphinx.ext.intersphinx',
    'sphinx.ext.viewcode',
    'numpydoc',
    'sphinx_rtd_theme',
    'sphinx.ext.napoleon',
    'recommonmark'
]

autosummary_generate = True
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']

# At the bottom of conf.py
def setup(app):
    app.add_config_value('recommonmark_config', {
            'url_resolver': lambda url: github_doc_root + url,
            'auto_toc_tree_section': 'Contents',
            }, True)
    app.add_transform(AutoStructify)

Answer 1

默认情况下，您必须包含外部链接协议。

但是，如果您想使用没有协议的裸链接，请使用Linkify：

将“linkify”添加到myst_enable_extensions（在 sphinx 中 conf.pyconfiguration file）将自动识别“裸”网址并添加超链接：

www.example.com -> www.example.com

此扩展需要安装linkify-it-py。要么直接； pip install linkify-it-py 或通过pip install myst-parser[linkify]。

以下代码示例演示了文档描述的内容。

myst_enable_extensions = [
    "linkify",
]