Sphinx文檔和Markdown鏈接

Question

我正在嘗試使用Sphinx從Markdown源構建一些文檔。 我的conf.py如下...

conf.py

from recommonmark.parser import CommonMarkParser
project = 'DS'
copyright = '2018, DS'
author = 'DS, Work'

version = ''
release = ''

extensions = []

templates_path = ['_templates']

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

master_doc = 'index'

language = None
exclude_patterns = []
pygments_style = 'sphinx'
html_theme = 'classic'
html_static_path = ['_static']
source_parsers = {
   '.md': CommonMarkParser,
}
htmlhelp_basename = 'DSDocumentationdoc'
latex_elements = {
}
latex_documents = [
    (master_doc, 'DSDocumentation.tex', 'DS Documentation',
     'DS, Work', 'manual'),
]
man_pages = [
    (master_doc, 'dsdocumentation', 'DS Documentation',
     [author], 1)
]
texinfo_documents = [
    (master_doc, 'DSDocumentation', 'DS Documentation',
     author, 'DSDocumentation', 'One line description ofproject.',
 'Miscellaneous'),
]

索引

Welcome to DS Documentation!
======================================

The following documentation is produced and maintained by the Data Science team.

Contents:

.. toctree::
   :maxdepth: 2
   :glob:

   README.md
   documentation.md
   getting_started/*
   how-tos/*
   statistics_data_visualisation.md

文檔生成並生成html輸出，但是README.md在兩個子目錄中具有指向其他markdown文檔的鏈接，例如：

... [this document](./getting_started/setting_your_machine_up.md)...

...在翻譯的README.html文檔中，該目標尚未轉換為翻譯的HTML目標，因為它已被識別為reference external ...

...<a class="reference external" href="./getting_started/setting_your_machine_up.md">this document</a>...

...我半期待/希望它會作為reference internal輸出並適當地轉換文件擴展名...

...<a class="reference internal" href="./getting_started/setting_your_machine_up.html">this document</a>...

...以使鏈接的工作方式與目錄在側邊欄中的作用相同。

關於是否可以實現的任何建議將不勝感激。

干杯。

編輯

嘗試通過@waylan我已經加入以下內容所建議的解決方案conf.py到enable_auto_doc_ref ...

def setup(app):
    app.add_config_value('recommonmark_config', {
        'enable_auto_doc_ref': True,
    }, True)
    app.add_transform(AutoStructify)

...並且在運行make html出現以下錯誤.....

❱ cat /tmp/sphinx-err-57rejer3.log 
# Sphinx version: 1.8.0
# Python version: 3.6.6 (CPython)
# Docutils version: 0.14 
# Jinja2 version: 2.10
# Last messages:
#   building [mo]: targets for 0 po files that are out of date
#   
#   building [html]: targets for 16 source files that are out of date
#   
#   updating environment:
#   
#   16 added, 0 changed, 0 removed
#   
#   reading sources... [  6%] README
#   
# Loaded extensions:
#   sphinx.ext.mathjax (1.8.0) from /home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/sphinx/ext/math
jax.py                                                                                                                                
#   alabaster (0.7.11) from /home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/alabaster/__init__.py
Traceback (most recent call last):
  File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/sphinx/cmd/build.py", line 304, in build_ma
in                                                                                                                                    
    app.build(args.force_all, filenames)
  File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/sphinx/application.py", line 341, in build
    self.builder.build_update()
  File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 347, in 
build_update                                                                                                                          
    len(to_build))
  File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 360, in 
build                                                                                                                                 
    updated_docnames = set(self.read())
  File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 468, in 
read                                                                                                                                  
    self._read_serial(docnames)
  File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 490, in 
_read_serial                                                                                                                          
    self.read_doc(docname)
  File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 534, in 
read_doc                                                                                                                              
    doctree = read_doc(self.app, self.env, self.env.doc2path(docname))
  File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/sphinx/io.py", line 318, in read_doc
    pub.publish()
  File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/docutils/core.py", line 218, in publish
    self.apply_transforms()
  File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/docutils/core.py", line 199, in apply_trans
forms                                                                                                                                 
    self.document.transformer.apply_transforms()
  File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/sphinx/transforms/__init__.py", line 90, in
 apply_transforms                                                                                                                     
    Transformer.apply_transforms(self)
  File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/docutils/transforms/__init__.py", line 171,
 in apply_transforms                                                                                                                  
    transform.apply(**kwargs)
  File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/recommonmark/transform.py", line 325, in ap
ply                                                                                                                                   
    self.traverse(self.document)
  File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/recommonmark/transform.py", line 297, in tr
averse                                                                                                                                
    self.traverse(child)
  File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/recommonmark/transform.py", line 297, in tr
averse                                                                                                                                
    self.traverse(child)
  File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/recommonmark/transform.py", line 297, in tr
averse                                                                                                                                
    self.traverse(child)
  File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/recommonmark/transform.py", line 287, in tr
averse                                                                                                                                
    newnode = self.find_replace(c)
  File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/recommonmark/transform.py", line 267, in fi
nd_replace                                                                                                                            
    newnode = self.auto_doc_ref(node)
  File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/recommonmark/transform.py", line 175, in au
to_doc_ref                                                                                                                            
    return self.state_machine.run_role('doc', content=content)
  File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/recommonmark/states.py", line 134, in run_r
ole                                                                                                                                   
    content=content)
TypeError: 'NoneType' object is not callable

我瀏覽了最后兩個電話，我認為這可能index.rst未設置content ，這可能與index.rst但我確實不在這里。

Answer 1

recommonmark文檔建議通過將以下內容添加到config.py文件中來啟用AutoStructify ：

from recommonmark.transform import AutoStructify

github_doc_root = 'https://github.com/rtfd/recommonmark/tree/master/doc/'
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)

這將為您提供以下功能：

• enable_auto_toc_tree ：是否啟用自動Toc樹功能。
• auto_toc_tree_section ：啟用時，僅在與標題匹配的部分上啟用“自動Toc樹”。
• enable_auto_doc_ref ：是否啟用自動文檔參考功能。
• enable_math ：是否啟用數學公式
• enable_inline_math ：是否啟用內聯數學
• enable_eval_rst ：是否啟用Embed reStructuredText。
• url_resolver ：將文檔中現有的相對位置映射到http鏈接的函數

值得注意的是自動文檔引用功能：

通常在一個文檔中引用另一文檔頁面。 我們通常使用引用來做到這一點。 AutoStructify會將這些參考塊轉換為結構化文檔參考。 例如

 [API Reference](api_ref.md) 

將轉換為以下reStructuredText代碼的AST

 :doc:`API Reference </api_ref>` 

並將其呈現為API參考

為什么這是必要的？ 因為與Rst不同，Markdown對給定文檔之外的任何內容都不了解，也不支持Rst樣式指令。 因此，沒有轉換URL的機制。

相反，AutoStructify會等到重新標記橋將Markdown轉換為Sphinx的基礎文檔結構（docutils文檔對象）之后，然后在其上運行一系列轉換器以提供有限的Rst類似功能。 即使使用AutoStructify，使用Markdown時也永遠不會獲得全部功能支持。 這將要求Markdown具有對指令的本機支持，這是不可能發生的。