php कोड प्रलेखन के लिए स्फिंक्स

Question

स्फिंक्स एक पाइथन पुस्तकालय है जो आरएसटी स्वरूपित पाठ फ़ाइलों के एक सेट से अच्छा दस्तावेज उत्पन्न करने के लिए है। पूर्ण पाठ खोज

के लिए उपयोग किया जाने वाला टूल नहीं, मैं डॉक्सिजन/phpdoc उपकरणों से पूरी तरह से अवगत हूं। मैं यह पता लगाने की कोशिश कर रहा हूं कि PHP परियोजनाओं को दस्तावेज करने के लिए स्फिंक्स का उपयोग करने का कोई तरीका है या नहीं? या यहां तक ​​कि किसी भी अन्य गैर पायथन भाषाओं?

http://sphinx.pocoo.org/

Answer 1

स्फिंक्स और बाकी मेरे अनुभव में, सामान्य प्रलेखन औजार के रूप में इस्तेमाल किया जा सकता। स्फिंक्स के बारे में कुछ भी नहीं है जो आपको केवल पायथन-आधारित परियोजनाओं के लिए इसका उपयोग करने के लिए बाध्य करता है। उदाहरण के लिए, मेरे काम में, मैंने इसे उपयोगकर्ता मार्गदर्शिका और एक्सएमएल-आरपीसी एपीआई संदर्भ बनाने के लिए उपयोग किया है। दोनों मामलों में, मेरे पास sphinx.ext.autodoc या अन्य पायथन-विशिष्ट एक्स्ट्रा के लिए कोई उपयोग नहीं था। स्पिंक्स द्वारा प्रदान किए गए विशेष निर्देशों के बजाए दस्तावेज "हाथ से" लिखा गया था, ज्यादातर जेनेरिक रीस्ट निर्देशों के साथ। इसके लायक होने के लिए, मुझे अभी तक गैर-पायथन दस्तावेज़ों के लिए कस्टम रीस्ट निर्देश बनाने की आवश्यकता नहीं है।

भले ही आप एक PHP परियोजना के साथ काम कर रहे हों, मुझे लगता है कि आपको स्फिंक्स उपयोगी लगेगा। उदाहरण के लिए the module specific markup द्वारा प्रदान किए गए अधिकांश निर्देश वास्तव में काफी सामान्य हैं। मुझे नहीं लगता कि आप पाइथन के अलावा अन्य भाषाओं से दस्तावेज़ों को दस्तावेज करने के लिए इन संरचनाओं का उपयोग क्यों नहीं कर सकते थे या नहीं। इसी प्रकार, स्फिंक्स show code examples in other languages के लिए यह बहुत आसान बनाता है। डिफॉल्ट को किसी भी भाषा में बदलने के लिए कॉन्फ़िगरेशन मान भी है जो पाइगल्स का समर्थन करता है (जिसमें PHP शामिल है)। यदि आप विशेष रूप से महत्वाकांक्षी महसूस कर रहे हैं, तो आप अपने PHP कोड से कुछ प्रासंगिक बनाने के लिए create a Sphinx extension भी कर सकते हैं।

जो कुछ भी कहा गया है, अपने दस्तावेज़ प्रोजेक्ट के लिए दर्शकों पर विचार करना सुनिश्चित करें। जबकि मुझे लगता है कि स्फिंक्स एक उत्कृष्ट उपकरण है और दस्तावेज परियोजनाओं की एक विस्तृत श्रृंखला के लिए इसकी सिफारिश करेगा, यदि आपके दर्शक कुछ और उम्मीद कर रहे हैं, तो इसके बारे में सावधान रहें। उदाहरण के लिए, यदि आप जावा प्रोजेक्ट को दस्तावेज कर रहे थे, तो आपके अधिकांश दर्शक जावाडोक-स्टाइल दस्तावेज़ों की अपेक्षा कर सकते हैं। यदि आप उस उम्मीद से विचलित हो जाते हैं, तो सुनिश्चित करें कि यह सिर्फ किक्स के लिए नहीं है (यानी, यह आपको बेहतर दस्तावेज देता है जो आपको अन्यथा मिलते हैं) और (संक्षेप में) जो आपने अलग-अलग किया है उसके लिए केस तैयार करने के लिए तैयार रहें (उदाहरण के लिए अक्सर पूछे जाने वाले प्रश्न या परिचय)।

आखिरकार, कोई भी दस्तावेज़ीकरण दस्तावेज से बेहतर है, भले ही उपकरण उन्हें बनाने के लिए उपयोग किया जाता है। किसी भी उपकरण का उपयोग करें जो आपकी मदद करता है, अगर यह वहां कुछ पाने के बीच अंतर है और नहीं।

Answer 2

बस जारी की कुछ दिन पहले: http://mark-story.com/posts/view/sphinx-phpdomain-released

Answer 3

सिद्धांत परियोजना, पीएचपी के लिए एक ORM, स्फिंक्स का उपयोग करता www.doctrine-project.org में अपने ऑनलाइन प्रलेखन उत्पन्न करने के लिए। वे PHP के लिए एक कस्टम पायगमेंट का उपयोग करें। दस्तावेज https://github.com/doctrine/orm-documentation पर गिथब पर उपलब्ध है। इसमें कस्टम PHP पायगमेंट सीएसएस फ़ाइल शामिल है।

इसके अलावा अजगर-pygments पैकेज कई pygment शैलियों जो आप अपने स्फिंक्स conf.py विन्यास फाइल में pygments_style = मान बदलकर बाहर कोशिश कर सकते हैं के साथ आता है। उदाहरण के लिए, pastie हाइलाइटिंग sytle, जो अजगर-pygments का हिस्सा है आज़माने के लिए, आप

pygments_sytle = 'pastie' 

Answer 4

CakePHP अपनी नई प्रलेखन के लिए स्फिंक्स उपयोग कर रहा है का उपयोग करें, और मैं स्फिंक्स के लिए phpdomain लिखा था। हालांकि sphinx में अपने php दस्तावेज़ ब्लॉक को स्वचालित रूप से शामिल करने का कोई तरीका नहीं है, फिर भी मुझे लगता है कि यह बेहतर प्रलेखन संलेखन उपकरण में से एक है। अधिक कथा शैली दस्तावेज के लिए यह महान है।लेकिन phpdomain के साथ आप एपीआई दस्तावेज़ भी बना सकते हैं।

Answer 5

जहां तक ​​मेरा संबंध है, आप स्पिंक्स में किसी भी वाक्यविन्यास के बारे में दस्तावेज कर सकते हैं, जहां तक ​​आप ऑटोडोक द्वारा समर्थित भाषाओं के साथ स्वयं को सीमित नहीं करते हैं। आप .. class, .. method, .. function और अन्य जैसे मानक स्फिंक्स निर्देशों का उपयोग करके सुंदर API संदर्भ बना सकते हैं। वे स्रोत कोड से पूरी तरह से अलग काम करते हैं और किसी भी स्वचालित पीढ़ी की आवश्यकता नहीं होती है और स्रोतों से जुड़ती है।

तुम भी कुछ खास वर्ग के साथ सामान्य admonitions बना सकते हैं, जिसे आप बाद में सीएसएस के लिए हुक कर सकते हैं:

.. admonition Title 
    :class: Ololo 

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

वहाँ भी भूमिकाएँ हैं और कुछ विशेष के साथ पाठ जोड़ने के अन्य साधन (वे कस्टम कक्षाएं भी अनुमति देता है) स्वरूपण, यदि मूल निर्देश आपके लिए पर्याप्त नहीं हैं।

यदि आप स्रोत कोड से अपने दस्तावेज़ एसिंक बनाने का निर्णय लेते हैं, तो सुनिश्चित करें कि आप अपने conf.py या प्रोजेक्ट दीक्षा पर कोड कवरेज और अन्य कोड-संबंधित सुविधाओं की जांच अक्षम कर दें।

पीएस: आप कस्टम कक्षाओं here के साथ तत्वों पर एक बहुत अच्छा जवाब देख सकते हैं।

Answer 6

जैसा कि आप देख वहाँ उपकरण इस के साथ मदद करने के लिए की एक बहुत कुछ है, अन्यथा, यदि आप वास्तव में जरूरत है, अभी देखें:

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