الهجرة من جافادوك إلى وثائق بيثون

Question

لذلك اعتدت إلى حد ما على توثيق نمط جافادوك. من خلال النظر من خلال أمثلة مختلفة من رمز Python ، أجد ذلك ، في البداية ، الوثائق يبدو أن تفتقد الكثير من المعلومات.

الخير: نادراً ما ترى أجزاء من الوثائق البديهية. عادة ما تكون Docstrings فقرة أو أقل من الترميز الإنجليزي الذي يدمج بدلاً من الوقوف على خطوط منفصلة.

السيئة: بالتزامن مع بطة Python ، أجد أن العديد من الوظائف غير واضحة حول المعلمات التي يتوقعونها. لا يوجد أي نوع من التلميحات (ميزة البط؟) وغالبًا ما يكون من الجيد أن يكون لديك فكرة أن المعلمة يجب أن تكون تشبه القائمة ، تشبه السلسلة ، تشبه الدفق.

بطبيعة الحال ، تم تصميم Javadoc للغة ذات المستوى الأدنى ، دون قدرات التأمل كبيرة للبيثون ، والتي قد تفسر فلسفة الوثائق الأقل مطولاً.

أي نصيحة بشأن معايير وثائق بيثون وأفضل الممارسات؟

Answer 1

ال إعادة هيكلة النص تم تصميم التنسيق استجابة للحاجة إلى وثائق بيثون التي يمكن تضمينها في docstrings ، وبالتالي فإن أفضل شيء هو تعلم الراحة وتنسيق docstrings الخاص بك مع هذا التنسيق. قد تجد ، كما فعلت ، أنك بعد ذلك تنسيق فقط أي الوثائق في الراحة ، ولكن هذه نقطة جانبية :-)

لتوثيق رمز Python الخاص بك على وجه التحديد أبو الهول النظام عبارة عن مجموعة من الامتدادات لتنسيق REST ، ونظام بناء لتقديم المستندات. نظرًا لأنه تم تصميمه لتوثيق Python نفسه ، بما في ذلك المكتبة القياسية ، يسمح Sphinx بتوثيق جيد التنظيم من رمز المصدر, ، بما في ذلك بالطبع تفاصيل توقيعات الوظيفة كما تسأل. يسمح ببناء جناح توثيق شامل ، سواء تم استخلاصه تلقائيًا أو مكتوبًا يدويًا ، وكل ذلك باستخدام نظام التنسيق نفسه.

اذا أنت فقط تريد الوثائق التي تم إنشاؤها من رمز المصدر الخاص بك ، ثم epydoc سيتم استخراج وثائق API من رمز المصدر الخاص بك; ؛ إنه أيضًا يقرأ تنسيق الراحة للنص.