用於php代碼文檔的Sphinx

Question

Sphinx是一個Python庫，用於從一組ReST格式的文本文件生成漂亮的文檔。不是用於全文搜索的工具

我也完全瞭解doxygen/phpdoc工具。我試圖弄清楚是否有一種使用Sphinx來記錄php項目的方法？甚至是任何其他非Python語言？

http://sphinx.pocoo.org/

Answer 1

獅身人面像和其餘的可以用作通用文檔工具，在我的經驗。 Sphinx沒有任何義務要求您僅將其用於基於Python的項目。例如，在我的工作中，我用它來構建用戶指南和XML-RPC API參考。在這兩種情況下，我都沒有使用sphinx.ext.autodoc或其他Python特有的附加功能。文檔是「手工編寫」的，大多數是通用的ReST指令，而不是Sphinx提供的專業指令。對於它的價值，我還不需要爲非Python文檔創建自定義的ReST指令。

即使你正在使用PHP項目，我想你會發現Sphinx很有用。例如，the module specific markup提供的大多數指令實際上是相當一般的。我不明白爲什麼你不能或不會使用這些結構來記錄Python以外的其他語言的東西。同樣，斯芬克斯很容易讓show code examples in other languages。甚至有一個配置值可以將默認值更改爲Pygments支持的任何語言（包括PHP）。如果你感覺特別宏偉，你甚至可以從你的PHP代碼中挑選相關的東西。

所有這一切，一定要考慮你的文檔項目的觀衆。雖然我認爲獅身人面像是一個很好的工具，並且會推薦它用於廣泛的文檔項目，但如果您的觀衆期待別的東西，請注意這一點。例如，如果你正在記錄一個Java項目，你的很多觀衆可能會期待Javadoc風格的文檔。如果你偏離了這個期望，確保它不僅僅是踢腿（也就是說，它會給你更好的文檔，否則你會得到更好的文檔），並準備（簡要地）說明你所做的不同之處（例如用常見問題回答或介紹）。

最後，無論用於創建它們的工具，任何文檔都比無文檔更好。使用任何可以幫助你的工具，如果這是獲得某種東西而不是獲得某種東西的區別。

Answer 2

剛剛發佈的前幾天： http://mark-story.com/posts/view/sphinx-phpdomain-released

Answer 3

學說項目，爲PHP的ORM，使用獅身人面像生成其在www.doctrine-project.org在線文檔。他們使用PHP的自定義分段。該文檔可在Github上獲得，網址爲https://github.com/doctrine/orm-documentation。它包括自定義的PHP python css文件。

另外，蟒蛇，Pygments來做包附帶了許多pygment的風格，你可以通過在獅身人面像conf.py配置文件改變pygments_style =值嘗試。例如，要嘗試一下pastie高亮sytle，這是蟒蛇，Pygments來做的一部分，您使用

pygments_sytle = 'pastie' 

Answer 4

CakePHP會使用獅身人面像其新的文檔，我寫了phpdomain的獅身人面像。雖然沒有辦法自動將你的php文檔塊包含到獅身人面像中，但我仍然認爲它是可用的更好的文檔編輯工具之一。它非常適合更多敘事風格的文檔。但是使用phpdomain，你也可以製作api文檔。

Answer 5

就我而言，只要您不用autodoc支持的語言來限制自己，就可以在Sphinx中記錄任何語法。您可以使用標準斯芬克斯指令（如.. class,.. method,.. function等）創建漂亮的API參考。它們完全獨立於源代碼工作，不需要任何自動生成和鏈接到源代碼。

您還可以創建通用的告誡一些特殊類，你可以在以後掛鉤的CSS：

.. admonition Title 
    :class: Ololo 

    This text could be formatted any way you want, using the ``Ololo`` tag. 

也有角色（他們讓太多的自定義類），並與一些特殊的添加文字等手段格式化，如果原始指令不足以滿足您的要求。

如果您決定從源代碼創建文檔異步，請確保您禁用了在您的conf.py中或項目啓動時檢查代碼覆蓋率和其他代碼相關功能。

PS：您可以在自定義類here的元素上看到非常好的答案。

Answer 6

正如你看到有很多的工具來幫助你這一點，否則，如果你真的需要，檢查出來：

https://blog.simpleigh.com/2012/08/php-documentation-and-sphinx