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 का निर्माण करता है

लिंक में यूआरआई क्वेरी पैरामीटर शामिल न करें:

  • उपयोग करें: <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 का उपयोग करना पसंद करें।

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

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

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

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

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

  • `tf.metrics` , `tf_agents.metrics` , `text.metrics` उत्पन्न करता है: tf.metrics , tf_agents.metrics , text.metrics ।

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

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

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

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

ऑप्स

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

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

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

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

टेंसर

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

एकाधिक Tensor ऑब्जेक्ट का वर्णन करने के लिए Tensors (बहुवचन) शब्द का उपयोग न करें जब तक कि आप वास्तव में 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 के साथ एक एकल अक्ष होता है।