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

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

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

markdown

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

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

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

पाठ में उपयोग किए जाने पर निम्नलिखित प्रतीकों के चारों ओर `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 पर सभी लिंक काम करते हैं। साथ ही, पाठक किसी लिंक पर क्लिक करने पर उसी साइट पर रहता है।

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

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

tensorflow.org से लिंक करते समय, मार्कडाउन लिंक पर एक {:.external} शामिल करें ताकि "बाहरी लिंक" प्रतीक दिखाया जा सके।

  • [GitHub](https://github.com/tensorflow/docs){:.external} GitHub का निर्माण करता है

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

  • उपयोग करें: <a href="https://www.tensorflow.org/guide/data">https://www.tensorflow.org/guide/data</a>
  • नहीं: <a href="https://www.tensorflow.org/guide/data?hl=en">https://www.tensorflow.org/guide/data?hl=en</a>

इमेजिस

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

आम तौर पर, आपको छवियों की जांच नहीं करनी चाहिए, और इसके बजाय अपने पीआर में TensorFlow-Docs टीम को जोड़ना चाहिए, और उन्हें tensorflow.org पर छवियों को होस्ट करने के लिए कहना चाहिए। यह आपके भंडार के आकार को कम रखने में मदद करता है।

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

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

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

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

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

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

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

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

  • MathJax tensorflow.org पर ठीक से प्रस्तुत करता है।
  • मैथजैक्स गिटहब पर ठीक से प्रस्तुत नहीं करता है।
  • अपरिचित डेवलपर्स के लिए यह संकेतन ऑफ-पुट हो सकता है।
  • निरंतरता के लिए tensorflow.org ज्यूपिटर/कोलाब के समान नियमों का पालन करता है।

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

उपयोग गाइड

ऑप्स

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

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

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

API संदर्भ में दस्तावेज़ परिणाम दिखाने के लिए doctest का उपयोग करना पसंद करते हैं।

टेंसर

जब आप सामान्य रूप से एक टेंसर के बारे में बात कर रहे हों, तो टेंसर शब्द को कैपिटलाइज़ न करें। जब आप उस विशिष्ट ऑब्जेक्ट के बारे में बात कर रहे हैं जो किसी ऑप को प्रदान किया गया है या लौटाया गया है, तो आपको Tensor शब्द को कैपिटल करना चाहिए और इसके चारों ओर बैकटिक्स जोड़ना चाहिए क्योंकि आप एक 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 के साथ एक धुरी होती है।