आप अपना पैकेज दस्तावेज कैसे लिखते हैं?

Question

मुझे पैकेज बनाने और उनके दस्तावेज़ लिखने के लिए एक समझदार वर्कफ़्लो नहीं मिला है।

मैं जितनी अधिक प्रक्रिया (और दस्तावेज) को स्वचालित रूप से जेनरेट करना चाहता हूं, उतना ही चाहता हूं।

यह करने के लिए स्पष्ट तरीका package.skeleton उपयोग करने के लिए बुनियादी पैकेज फ़ाइलें बनाने के लिए है, तो प्रोग्राम के रूप में DESCRIPTION फ़ाइल और Rd फ़ाइलों को अधिलेखित हो रहा है। इसके साथ समस्या यह है कि आप स्वचालित रूप से जेनरेट किए गए फ़ील्ड को खो देते हैं जो सुनिश्चित करते हैं कि आपको सभी सही पैरामीटर दस्तावेज करने के लिए याद किया गया है।

मुझे यह जानना है कि आप पैकेज बनाने और दस्तावेज़ लिखने के बारे में जानें। क्या प्रक्रिया को आसान बनाने के लिए कोई उपकरण उपलब्ध है? (roxygen ऐसा लगता है कि यह इस तरह की चीज़ के लिए डिज़ाइन किया गया था; क्या इसके लिए कोई अच्छा ट्यूटोरियल है? और क्या कोई विकल्प हैं?)

Answer 1

मैं अपनी सभी परियोजनाओं के लिए roxygen का उपयोग करता हूं। उदाहरण के लिए, the webvis package के लिए स्रोत ब्राउज़ करें। हैडली अपने दस्तावेज़ीकरण के लिए roxygen का भी उपयोग करता है (उदा। उसके lubridate package देखें)।

मेरे सबसे अच्छे ज्ञान के लिए, roxygen को विगेट से बहुत अधिक दस्तावेज नहीं किया गया है (the roxygen homepage पर एक नज़र डालें)।

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

यह कहा गया है कि यह दस्तावेज को स्वचालित रूप से स्वचालित नहीं करता है कि कुछ दस्तावेज-पीढ़ी के उपकरण (उदा। जावाडोक) करते हैं: roxygen आर टिप्पणियों की व्याख्या करता है जो उचित रूप से स्वरूपित होते हैं, लेकिन यह किसी भी तरह से आर कोड की व्याख्या नहीं करता है।

आमतौर पर पैकेज के निर्माण के संबंध में: package-skeleton शुरुआत करने वालों के लिए बहुत अच्छा है। एक बार जब आप कुछ पैकेज तैयार कर लेते हैं तो आपको भविष्य में सभी निर्देशिकाएं, NAMESPACE इत्यादि बनाने के लिए भविष्य में यह आसान हो सकता है। विशेष रूप से यदि आप कुछ अन्य प्रथाओं का पालन करने जा रहे हैं, जैसे डेमो निर्देशिका, रॉक्सीजन का उपयोग करके, एक विगनेट लिखना, या अन्य भाषाओं में स्रोत कोड समेत।

आखिरकार, मैं ग्रहण (स्टेटेट) में अपने पैकेज प्रबंधित करता हूं; आईडीई के कई "प्रोजेक्ट" विचार हैं जो पैकेज संरचना को प्रबंधित करने में मदद करते हैं, ताकि आप एक और उन्नत संपादक का उपयोग भी कर सकें।

Answer 2

के बारे में roxygen संसाधन, कई और अधिक के बाद से उभरा है, कुछ और उभरा है, my own notes उद्धृत करने के लिए:

अक्सर जब मैं Roxygen या Roxygen2 गूगल मैं मुसीबत प्रलेखन खोजने की है।यहां कुछ प्रमुख संसाधनों का एक संकलन है:

• हैडली विकहैम है एक महान introduction to core features of Roxygen 2

• हैं several vignettes listed on the Cran site for Roxygen 2

• RStudio running Roxygen

• roxygen2 package source code on github

पर नोट है 210