🏽 ⏳ 🌏 Docblox - कुछ नवाचार 🏩 🚴🏼 💄

यह आलेख Docblox , PHP 5.3+ के लिए प्रलेखन प्रणाली द्वारा सुझाए गए कुछ नवाचारों पर करीब से नज़र डालता है । कुछ चीजों को समझने के लिए, आपको पिछले लेख को पढ़ने की आवश्यकता है। सादगी के लिए, मैंने परीक्षण स्रोतों के साथ एक निर्देशिका के रूप में / src / example / ( / src - real निर्देशिका के लिए अपने स्रोत कोड के साथ) का उपयोग किया।

अतिरिक्त लाइब्रेरी स्थापित करें

काम के लिए, हमें कुछ अतिरिक्त पुस्तकालयों की आवश्यकता है। उन्हें स्थापित करें।

यदि आपके पास PHP XSL एक्सटेंशन स्थापित नहीं है, तो Docblox आपको सूचित करेगा कि HTML प्रारूप में प्रलेखन नहीं बनाया जा सकता है। आप इस एक्सटेंशन को स्थापित कर सकते हैं, उदाहरण के लिए, इस तरह:
```
# apt-get install php5-xsl # apachectl restart (   Apache) 
```
क्लास ग्राफ बनाने के लिए, आपको ग्राफविज़ को भी इंस्टॉल करना होगा:
```
 # apt-get install graphviz 
```
पीडीएफ प्रलेखन उत्पन्न करने के लिए, आपको wkhtmltopdf लाइब्रेरी की आवश्यकता है:
```
 # apt-get install wkhtmltopdf 
```

पार्सर डेटा के साथ इंटरमीडिएट XML फ़ाइल

हमें शुरुआत के लिए एक परीक्षण मामले की आवश्यकता होगी, उत्पन्न XML फ़ाइल की संरचना को समझने के लिए PHP डॉक्यूमेंट के परिचित @ -tags, जो वर्तमान में परियोजना की आधिकारिक वेबसाइट पर प्रलेखित नहीं है। Example.php फ़ाइल लें जिसमें उदाहरण वर्ग है:

 /** * Example class file short description. * * @package file.package * @author Vania-pooh <vania-pooh@myemail.com> * @link http://www.myexampleclass.com/ * @copyright Copyright © 2011 Vania-pooh * @license http://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt LGPL */ namespace \ExampleNS; /** * Example class short description. * * Example class long description. * Lorem ipsum dolor sit amet, consectetur adipiscing elit. * Nunc mollis leo felis, nec euismod nulla. * Vivamus condimentum vehicula consequat. * * @author Vania-pooh <vania-pooh@myemail.com> * @package class.package * @since 1.0 */ class Example extends ParentExample { /** * @var string public property description. Defaults to 'publicValue'. * @static * @Column(type="string", length=32, unique=true, nullable=false) */ public static $publicProp = 'publicValue'; /** * @var int private property description. */ private $privateProp = 1; /** * @var boolean protected property description. */ protected $protectedProp = false; /** * Public function short description. * * Public function long description. * @param boolean $param1 param1 short description. * @param string $param2 param2 short description. */ public function doIt($param1, $param2) { //... } }

आइए Docblox के लिए एक सरल docblox.xml कॉन्फ़िगरेशन फ़ाइल बनाएं, जहाँ हम स्पष्ट रूप से निर्दिष्ट करते हैं कि हमें XML फ़ाइल को कहाँ सहेजना है। इसके अलावा, हम / src / example directory में दो डाइरेक्टरी बनाएंगे - डॉक्स और xml।

अब Docblox को / src / उदाहरण निर्देशिका में चलाएँ:

 $ cd /src/example $ docblox run

हमारे द्वारा आवश्यक संरचना .xml फ़ाइल फ़ोल्डर / src / example / xml / में बनाई जाएगी। आइए इसे और अधिक विस्तार से विचार करें। तो, एक सामान्य संरचना। Xml फ़ाइल में निम्न संरचना है:

 <?xml version="1.0"?><project version="0.14.0" title=""> <!--  hash    ,    MD5 --> <file path="Example.php" hash="8c6b0d4bc263fcf83499f57f1dcd9aa6" package="file\package"> <!--   docblock    file,       --> <docblock> <description>Example class file short description.</description> <long-description> </long-description> <!--    @-  --> <tag name="author" description="Vania-pooh <vania-pooh@myemail.com>"/> <!-- … --> </docblock> <!--    --> <class final="false" abstract="false" line="24" namespace="ExampleNS" package="class\package"> <name>Example</name> <extends>\ExampleNS\ParentExample</extends> <full_name>\ExampleNS\Example</full_name> <docblock> <description>Example class short description.</description> <long-description>--</long-description> <tag name="author" description="Vania-pooh <vania-pooh@myemail.com>" line="12"/> <tag name="package" description="class.package" line="12"/> <tag name="since" description="1.0" line="12"/> </docblock> <!--    --> <property final="false" static="true" visibility="public" line="30" package="Default"> <name>$publicProp</name> <default>publicValue</default> <docblock> <!-- @-   --></docblock> </property> <property final="false" static="false" visibility="private" line="35" package="Default"> <!-- @-   --> </property> <!--        → <!--   --> <method final="false" abstract="false" static="false" visibility="public" line="50" package="Default"> <name>doIt</name> <docblock> <!-- @-   doIt() --></docblock> <!--    --> <argument line="50"> <name>$param1</name> <default/> <type/> </argument> <argument line="50"> <name>$param2</name> <!--    --> </argument> </method> </class> </file> <package name="Default"/> <!--      --> <namespace name="ExampleNS"/> <marker>todo</marker> <marker>fixme</marker> </project>

उपरोक्त कोड को विशेष टिप्पणियों की आवश्यकता नहीं है। मैं केवल ध्यान देता हूं कि डॉकब्लॉक मार्कअप की पूरी सामग्री हमेशा <डॉकब्लॉक> </ डॉकब्लॉक> टैग के भीतर समाहित है। शेष टैग निष्पादन योग्य कोड के विश्लेषण के आधार पर प्राप्त मूल्यों का वर्णन करते हैं, न कि उस पर टिप्पणियों का। @ पैकेज टैग द्वारा निर्दिष्ट पैकेज के नाम के रूप में, इस टैग की अनुपस्थिति में, कमांड लाइन या docblox.xml फ़ाइल से डिफ़ॉल्ट-पैकेज-नाम पैरामीटर मान का उपयोग किया जाता है । यदि पैरामीटर निर्दिष्ट नहीं है, तो डिफ़ॉल्ट मान का उपयोग किया जाता है। जैसा कि आप देख सकते हैं, आप पूरी फ़ाइल के लिए अलग-अलग पैकेज नामों का उपयोग कर सकते हैं, कक्षा के लिए और एक अलग संपत्ति \ विधि के लिए।

थीम का उपयोग करना

Docblox विभिन्न कोड प्रदर्शन विषयों के निर्माण का समर्थन करता है। PEAR का उपयोग करके लाइब्रेरी स्थापित करते समय, थीम <PEAR_ROOT> / Docblox / data / themes निर्देशिका में स्थित होती हैं, जहां <PEAR_ROOT> सभी स्थापित PEAR पैकेजों के स्रोत कोड के लिए संग्रहण स्थान है (उदाहरण के लिए, Ubuntu में <PEAR_ROOT> यह / usr / share / php / ) है। । प्रत्येक विषय एक अलग निर्देशिका में स्थित है और इसमें एक टेम्पलेट। Xml फ़ाइल शामिल होनी चाहिए, जिसमें प्रलेखन विधानसभा नियम हैं। फ़ाइल में मुख्य रूप से लाइनें शामिल हैं:

 <transformation query="" writer="    " source="   " artifact="    " />

नियमों के उदाहरण:

सवाल	लेखक	स्रोत	विरूपण साक्ष्य
प्रतिलिपि	FileIO	क्या नकल करनी है?	कहां नकल करनी है
-	XSL	XSL टेम्पलेट	तैयार है HTML फाइल
-	ग्राफ़	गिनना क्या आकर्षित करना है	गणना svg फ़ाइल का नाम
-	पीडीएफ	HTML फ़ाइल का नाम	पीडीएफ फाइल नाम

Template.xml के अलावा, किसी भी विषय में XSL पेज टेम्प्लेट, कैस्केडिंग स्टाइल शीट, जेएस स्क्रिप्ट आदि शामिल हैं। इस प्रकार, यदि आप XSL टेम्प्लेट से परिचित हैं, तो आप आसानी से प्रलेखन प्रदर्शित करने के लिए एक नया विषय बना सकते हैं।

पीडीएफ प्रलेखन पीढ़ी

पीडीएफ डॉक्यूमेंट तैयार करना भी सीधा है। ऐसा करने के लिए, बस docblox.xml कॉन्फ़िगरेशन फ़ाइल में मानक पीडीएफ विषय का उपयोग करें:

 <transformations> <template name="pdf" /> </transformations>

Docblox शुरू करने के बाद, आप देखेंगे कि / src / example / docs / folder में (यदि कॉन्फ़िगरेशन फ़ाइल निर्दिष्ट दस्तावेज को बचाने के लिए कहां निर्दिष्ट नहीं करती है, तो डिफ़ॉल्ट रूप से वर्तमान निर्देशिका में आउटपुट निर्देशिका बनाई जाएगी) HTML पृष्ठों और आवश्यक फ़ाइल का एक सेट। apidocs.pdf। PDF

लेकिन हमने HTML बनाने के लिए नहीं कहा! सब कुछ सही है, हालांकि, डॉकबॉल्क्स wttmltopdf लाइब्रेरी का उपयोग करता है, जो केवल HTML को पीडीएफ में बदल सकता है, इसलिए आपको HTML पेज बनाने होंगे, जो तब एक सिंगल पीडीएफ फाइल में बदल जाते हैं। यदि आप एक ही फ़ोल्डर से index.html फ़ाइल को देखते हैं, तो आप देखेंगे कि यह बिल्कुल परिणामस्वरूप PDF फ़ाइल के समान है। इस प्रकार, HTML फ़ाइलों के डिज़ाइन को संशोधित करके, आप किसी भी उपस्थिति के पीडीएफ दस्तावेज़ बना सकते हैं। यह एक बहुत ही सुविधाजनक दृष्टिकोण है जो आपको एक ही ग्राफिक तत्वों और स्टाइल शीट से एक प्रोजेक्ट साइट और इसके प्रलेखन बनाने की अनुमति देता है।

यूएमएल ग्राफ जनरेशन

एक यूएमएल ग्राफ उत्पन्न करने के लिए, आपको उपयोग की गई थीम की सेटिंग में एक नियम जोड़ना होगा (टेम्पलेट.एक्सएमएल) निम्नानुसार है:

 <transformation query="" writer="Graph" source="Class" artifact="filename.svg" />

Docblox को / src / example / docs / में चलाने के बाद, आपको आवश्यक फ़ाइल आरेख वाली फ़ाइल filename.svg मिल जाएगी। UML-

यह आपको एक प्रलेखन फ़ाइल में एक वर्ग आरेख को एम्बेड करने की अनुमति देता है।

सिद्धांत @ टैग समर्थन

संस्करण 0.14 के साथ शुरू, डॉकब्लोक्स @ -टैग्स का समर्थन करता है जो प्रसिद्ध ओआरएम सिद्धांत का उपयोग करने के लिए उपयोग किया जाता है। हमारे परीक्षण वर्ग की $ publicProp संपत्ति में एक नया @ कॉलम जोड़ें उदाहरण:

 /** * @var string public property description. Defaults to 'publicValue'. * @static * @Column(type="string", length=32, unique=true, nullable=false) */

फ़ाइल को संसाधित करने के बाद, संरचना में एक नया ब्लॉक दिखाई देगा। xml:

 <tag name="Column" description="Column" plugin="doctrine" link="http://www.doctrine-project.org/docs/orm/2.1/en/reference/annotations-reference.html#annref-column" content="type="string", length=32, unique=true, nullable=false" line="26"> <argument field-name="type">"string"</argument> <argument field-name="length">32</argument> <argument field-name="unique">true</argument> <argument field-name="nullable">false</argument> </tag>

जैसा कि आप देख सकते हैं, Docblox स्वचालित रूप से डॉक्ट्रिन डॉक्यूमेंटेशन के संबंधित सेक्शन में एक लिंक जोड़ सकता है और टैग नोटेशन से टाइप किए गए मापदंडों को निकाल सकता है जैसे टाइप, लेंथ और अन्य। Doctrine @ टैग के लिए समर्थन जोड़ने से डॉकब्लॉक्स एक पायदान ऊंचा हो गया। हमें उम्मीद है कि इस उपयोगी परियोजना का विकास भविष्य में भी उतना ही सफल होगा।

संदर्भ

http://www.graphviz.org/ - ग्राफविज़ की आधिकारिक साइट
http://code.google.com/p/wkhtmltopdf/ - wkhtmltopdf पेज>
http://www.doctrine-project.org/docs/orm/2.0/en/reference/annotations-reference.html - @ डॉक्ट्रिन टैग का विवरण
http://ru.wikipedia.org/wiki/XSL - XSL पर अधिक
http://php.net/xsl - XSL के साथ काम करने के लिए PHP वर्ग

Docblox - कुछ नवाचार