使用Sphinx為Python項目生成幫助文檔

本文為前一篇 一個小而全的項目的延續：一個小而全的Python項目示例_持續學習持續開發，我是雷學委！-CSDN博客

安裝Sphinx（文檔生成工具）

pip install -U Sphinx

生成默認文檔配置

sphinx-quickstart

這里選擇了不分離代碼跟文檔。

生成文檔

sphinx-build -b html . _build

因為上面沒有選擇把代碼跟文檔分開，所以sphinx掃描了所有目錄而不是我們模塊的代碼，出現下面錯誤：

檢查一致性... /Users/mac/python/python_sample/lib/python3.8/site-packages/Jinja2-2.11.3.dist-info/LICENSE.rst: WARNING: 文檔沒有加入到任何目錄樹中

/Users/mac/python/python_sample/lib/python3.8/site-packages/MarkupSafe-1.1.1.dist-info/LICENSE.rst: WARNING: 文檔沒有加入到任何目錄樹中

該錯誤可以忽略，并不妨礙文檔生成。

查看默認生成的文檔

打開瀏覽器出入當前目錄/_build/index.html,? 即可查看。

Sphinx如何運作？

上面使用sphinx-quickstart 生成默認文檔聲明文件Makefile和conf.py, Makefile指定項目信息和source目錄（這里是sphinx的source）。

然后sphinx根據找到的source（*.rst, 后綴為.rst 文件)，并解析生成同名的html文件。

:ref 指定為上面index.html頁面的三個超鏈接，更多使用參考：

概述 — Sphinx 2.2.0 文檔

Python Sphinx

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