Sphinx+github+ReadtheDocs書寫筆記

項目很高端吧！廢話不多說，直接來

搭建本地環境

1、確保電腦已經安裝python運行環境

2、安裝 sphinx及其依賴

pip install sphinx sphinx-autobuild sphinx_rtd_theme recommonmark sphinx-markdown-tables

1

3、新建文件夾，運行cmd 創建工程

sphinx-quickstart

1

按照提示填寫三個信息，其他一般只用填寫

(Separate source and build directories): y

項目名稱(Project name) : EvaEngine

創建成功！

4、編譯文件

make clean # 清空 make html # 構建文檔

1

2

5、打開測試，打開如下路徑文件

\build\html\index.html

1

熟悉的界面，不熟悉也沒關系~~~

6、更換風格

打開conf.py 文件，做如下更換

# html_theme = 'alabaster' html_theme = 'sphinx_rtd_theme'

1

2

1

2

1

2

再次編譯文件（同第4步），頁面煥然一新

7、書寫文章

項目文件中根目錄中，新建page文件夾，新建 page.rst 文件

根據rst書寫規則書寫文章，例如：

新建的page頁面 ================================== 這是內容

1

2

3

4

5

再次編譯，訪問測試

8、上傳項目值github

將 整個項目 下的文件上傳至github

9、 導入到 ReadtheDocs

GitHub 里選擇倉庫，然后依次點擊 Setting => Webhooks & Service => Add service => ReadTheDocs,激活這個選項。

到 ReadtheDocs import 這個倉庫，導入成功后，點擊閱讀文檔，便可看到 Web 效果了。

遇到的問題

1、WARNING: document isn’t included in any toctree

將source/page下的所有文件包含進來

.. toctree:: :maxdepth: 2 :glob: page/*

1

2

3

4

5

2、支持markdown

打開conf.py 文件做修改

# source_suffix = '.rst' from recommonmark.parser import CommonMarkParser source_parsers = { '.md': CommonMarkParser, } source_suffix = ['.rst', '.md']

1

2

3

4

5

6

1

2

3

4

5

6

1

2

3

4

5

6

3、支持markdown的表格

pip install sphinx-markdown-tables

1

配置conf.py文件

依賴于recommonmark

extensions = [ 'sphinx_markdown_tables', ]

1

2

3

備注：

如果熟悉makedown，可以使用在線工具轉為rst文檔：

http://pandoc.org/try/

這是我新建的項目地址：

http://mynote-mouday.readthedocs.io

rst語法參考：

reStructuredText(rst)快速入門語法說明

參考

如何用 ReadtheDocs、Sphinx 快速搭建寫書環境

寫最好的文檔：Sphinx + Read the Docs

使用ReadtheDocs托管文檔

sphinx-markdown-tables 0.0.9

Git GitHub Sphinx

版權聲明：本文內容由網絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發現本站中有涉嫌抄襲或描述失實的內容，請聯系我們jiasou666@gmail.com 處理，核實后本網站將在24小時內刪除侵權內容。

版權聲明：本文內容由網絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發現本站中有涉嫌抄襲或描述失實的內容，請聯系我們jiasou666@gmail.com 處理，核實后本網站將在24小時內刪除侵權內容。