TensorFlow दस्तावेज़ीकरण शैली मार्गदर्शिका

सर्वोत्तम प्रथाएं

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

markdown

कुछ अपवादों को छोड़कर, TensorFlow GitHub Flavored Markdown (GFM) के समान Markdown सिंटैक्स का उपयोग करता है। यह अनुभाग GFM Markdown सिंटैक्स और TensorFlow दस्तावेज़ीकरण के लिए उपयोग किए जाने वाले Markdown के बीच अंतर बताता है।

कोड के बारे में लिखें

कोड का इनलाइन उल्लेख

पाठ में निम्नलिखित प्रतीकों का उपयोग करते समय उनके चारों ओर `backticks` लगाएं:

  • आर्गुमेंट के नाम: `input` , `x` , `tensor`
  • लौटाए गए टेंसर नाम: `output` , `idx` , `out`
  • डेटा प्रकार: `int32` , `float` , `uint8`
  • पाठ में संदर्भित अन्य ऑपरेशन नाम: `list_diff()` , `shuffle()`
  • क्लास के नाम: `tf.Tensor` , `Strategy`
  • फ़ाइल का नाम: `image_ops.py` , `/path_to_dir/file_name`
  • गणितीय अभिव्यक्तियाँ या शर्तें: `-1-input.dims() <= dim <= input.dims()`

कोड ब्लॉक

कोड ब्लॉक को खोलने और बंद करने के लिए तीन बैकटिक का उपयोग करें। वैकल्पिक रूप से, पहले बैकटिक समूह के बाद प्रोग्रामिंग भाषा निर्दिष्ट करें, उदाहरण के लिए:


```python
# some python code here
```

एक ही GitHub रिपॉजिटरी में फ़ाइलों के बीच रिलेटिव लिंक का उपयोग करें। फ़ाइल एक्सटेंशन शामिल करें।

उदाहरण के लिए, यह फ़ाइल जिसे आप पढ़ रहे हैं, https://github.com/tensorflow/docs रिपॉजिटरी से है। इसलिए, यह उसी रिपॉजिटरी में अन्य फ़ाइलों को लिंक करने के लिए सापेक्ष पथों का उपयोग कर सकती है, जैसे कि:

यह बेहतर तरीका है क्योंकि इससे tensorflow.org , GitHub और Colab पर मौजूद सभी लिंक काम करते हैं। साथ ही, लिंक पर क्लिक करने पर पाठक उसी साइट पर बने रहते हैं।

उन फ़ाइलों के लिंक के लिए जो वर्तमान रिपॉज़िटरी में नहीं हैं, पूर्ण URI के साथ मानक Markdown लिंक का उपयोग करें। यदि उपलब्ध हो तो tensorflow.org URI से लिंक करना बेहतर होगा।

सोर्स कोड से लिंक करने के लिए, https://www.github.com/tensorflow/tensorflow/blob/master/ से शुरू होने वाले लिंक का उपयोग करें, जिसके बाद GitHub रूट से शुरू होने वाला फ़ाइल नाम लिखें।

जब आप tensorflow.org से लिंक कर रहे हों, तो Markdown लिंक में `` शामिल करें ताकि "बाहरी लिंक" प्रतीक दिखाई दे।

  • [GitHub](https://github.com/tensorflow/docs) GitHub उत्पन्न करता है

लिंक में URI क्वेरी पैरामीटर शामिल न करें:

  • इस लिंक का उपयोग करें: https://www.tensorflow.org/guide/data
  • नोट: https://www.tensorflow.org/guide/data?hl=en

इमेजिस

पिछले अनुभाग में दी गई सलाह पृष्ठों के लिंक के लिए है। छवियों को अलग तरीके से संभाला जाता है।

सामान्यतः, आपको इमेज को रिपॉजिटरी में शामिल नहीं करना चाहिए, बल्कि अपने पीआर में टेन्सरफ्लो-डॉक्स टीम को जोड़ना चाहिए और उनसे टेन्सरफ्लो डॉट ओआरजी पर इमेज होस्ट करने का अनुरोध करना चाहिए। इससे आपके रिपॉजिटरी का आकार कम रखने में मदद मिलती है।

यदि आप अपनी रिपॉजिटरी में इमेज सबमिट करते हैं, तो ध्यान दें कि कुछ सिस्टम इमेज के रिलेटिव पाथ को हैंडल नहीं करते हैं। बेहतर होगा कि आप tensorflow.org पर इमेज के अंतिम स्थान को इंगित करने वाला पूरा URL उपयोग करें।

साइट प्रकाशित होने पर API लिंक परिवर्तित हो जाते हैं। किसी प्रतीक के API संदर्भ पृष्ठ से लिंक करने के लिए, प्रतीक पथ को बैकटिक के भीतर रखें:

  • `tf.data.Dataset` tf.data.Dataset उत्पन्न करता है

लंबे पथों को छोड़कर, पूर्ण पथों को थोड़ा अधिक प्राथमिकता दी जाती है। पथों के शुरुआती घटकों को हटाकर उन्हें संक्षिप्त किया जा सकता है। आंशिक पथों को लिंक में परिवर्तित कर दिया जाएगा यदि:

  • पथ में कम से कम एक . है, और
  • यह आंशिक पथ परियोजना के भीतर अद्वितीय है।

tensorflow.org पर प्रकाशित Python API वाले प्रत्येक प्रोजेक्ट के लिए API पथ लिंक किए गए हैं। आप API नामों को बैकटिक के साथ रैप करके एक ही फ़ाइल से कई सबप्रोजेक्ट्स को आसानी से लिंक कर सकते हैं। उदाहरण के लिए:

जिन प्रतीकों के एकाधिक पथ उपनाम होते हैं, उनमें tensorflow.org पर API पृष्ठ से मेल खाने वाले पथ को थोड़ी प्राथमिकता दी जाती है। सभी उपनाम सही पृष्ठ पर रीडायरेक्ट करेंगे।

मार्कडाउन में गणित

आप Markdown फ़ाइलों को संपादित करते समय TensorFlow के भीतर MathJax का उपयोग कर सकते हैं, लेकिन निम्नलिखित बातों का ध्यान रखें:

  • MathJax tensorflow.org पर ठीक से प्रदर्शित होता है।
  • MathJax GitHub पर ठीक से प्रदर्शित नहीं होता है।
  • यह संकेतन अपरिचित डेवलपर्स के लिए अरुचिकर हो सकता है।
  • एकरूपता बनाए रखने के लिए tensorflow.org, Jupyter/Colab के समान नियमों का पालन करता है।

MathJax के ब्लॉक के चारों ओर $$ का उपयोग करें:

$$
E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2
$$

\[ E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2 \]

इनलाइन MathJax एक्सप्रेशन को $ ... $ से लपेटें:


This is an example of an inline MathJax expression: $ 2 \times 2 = 4 $

यह एक इनलाइन MathJax एक्सप्रेशन का उदाहरण है: \( 2 \times 2 = 4 \)

\\( ... \\) विभाजक भी इनलाइन गणित के लिए काम करते हैं, लेकिन $ रूप कभी-कभी अधिक पठनीय होता है।

गद्य शैली

यदि आप कथात्मक दस्तावेज़ के महत्वपूर्ण हिस्सों को लिखने या संपादित करने जा रहे हैं, तो कृपया Google डेवलपर दस्तावेज़ीकरण शैली मार्गदर्शिका पढ़ें।

अच्छी शैली के सिद्धांत

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

उपयोग मार्गदर्शिका

ऑप्स

मार्कडाउन फ़ाइलों में, जब आप यह दिखाना चाहते हैं कि कोई ऑपरेशन क्या लौटाता है, तो केवल एक बराबर चिह्न के बजाय # ⇒ का उपयोग करें।

# 'input' is a tensor of shape [2, 3, 5]
tf.expand_dims(input, 0)  # ⇒ [1, 2, 3, 5]

नोटबुक में, टिप्पणी जोड़ने के बजाय परिणाम प्रदर्शित करें (यदि नोटबुक सेल में अंतिम अभिव्यक्ति किसी चर को असाइन नहीं की गई है, तो यह स्वचालित रूप से प्रदर्शित होती है)।

एपीआई संदर्भ दस्तावेज़ों में परिणाम दिखाने के लिए डॉक्टेस्ट का उपयोग करना बेहतर होता है।

टेंसर

जब आप सामान्य रूप से किसी टेंसर की बात कर रहे हों, तो 'टेंसर' शब्द को कैपिटल लेटर में न लिखें। लेकिन जब आप किसी ऑपरेशन को दिए गए या उससे प्राप्त होने वाले विशिष्ट ऑब्जेक्ट की बात कर रहे हों, तो 'टेंसर' शब्द को कैपिटल लेटर में लिखें और उसके चारों ओर बैकटिक लगाएं, क्योंकि आप एक Tensor ऑब्जेक्ट की बात कर रहे हैं।

जब तक आप वास्तव में किसी Tensors ऑब्जेक्ट की बात नहीं कर रहे हों, तब तक एकाधिक Tensor ऑब्जेक्ट्स का वर्णन करने के लिए Tensors (बहुवचन) शब्द का प्रयोग न करें। इसके बजाय, " Tensor ऑब्जेक्ट्स की एक सूची (या संग्रह)" कहें।

टेंसर के अक्षों का विवरण देने के लिए " आकार" शब्द का प्रयोग करें और आकार को वर्गाकार कोष्ठकों में बैकटिक के साथ दर्शाएँ। उदाहरण के लिए:


If `input` is a three-axis `Tensor` with shape `[3, 4, 3]`, this operation
returns a three-axis `Tensor` with shape `[6, 8, 6]`.

जैसा कि ऊपर बताया गया है, Tensor के आकार के तत्वों के बारे में बात करते समय "आयाम" के बजाय "अक्ष" या "सूचकांक" का प्रयोग करें। अन्यथा, "आयाम" को सदिश स्थान के आयाम से भ्रमित करना आसान है। एक "त्रि-आयामी सदिश" में 3 लंबाई का एक ही अक्ष होता है।