روابط إلى الأجزاء السابقة:
- الجزء الأول - مقدمة ، بدائل الرسوم البيانية اللازمة لإنشاء تمثيل رسومي للرمز
- الجزء الثاني - تنفيذ تمثيل رسومي لمولد الشفرة (يتم بشكل رئيسي في بيثون) ، لغة الترميز الجزئي
- الجزء الثالث - ميزات الرسومات الجديدة
يظهر مثال على بيئة تدعم هذا التمثيل الرسومي في الصورة أدناه.
بيئة دعم رمز الرسوميةسيركز الجزء الرابع من المقالة على دعم عملية التوثيق.
حول الأدغال
دعونا نرى ما هو متاح للمطور من حيث العمل مع الوثائق.
يدعم Python خطوط الوثائق للوحدات النمطية والفئات والوظائف. هذا جيد تستخدم التعليقات أيضًا في بعض الأحيان للتوثيق.
هناك مولدات الوثائق مثل
الأكسجين وأبو الهول . هذا جيد ايضا
ومع ذلك ، في بعض الأحيان تريد أكثر من ذلك بقليل. هناك أوقات يكون فيها وصف الوظيفة أو الفصل الدراسي كبيرًا جدًا و "تنتفخ" سطور الوثائق (أو التعليقات) بشكل غير ضروري. يبدأ عدد الخطوط غير القابلة للتنفيذ في منع عدد الخطوط القابلة للتنفيذ ، مما قد يجعل القراءة صعبة بسبب تشويش الكود. مشكلة أخرى هي الرسوم البيانية المختلفة. لا يمكنك إدراج صورة منتهية في النص. يمكنك فقط إدراج وصف للمخطط ، على سبيل المثال ، رسم تخطيطي لـ
UML ، ولكن حتى في هذه الحالة ، من الضروري تقديم التجسيد ، وهو أمر يصعب القيام به مباشرة في نص البرنامج.
حل المشكلة بسيط - لحفظ وصف مطول في ملف منفصل ، وترك ملاحظة في الكود بأن الوثائق موجودة. يمكن تقديم ملف واحد بشكل مناسب في الوقت المناسب. ويفضل أن تكون العلامة في الكود تفاعلية ، أي توفير انتقال إلى الوثائق بنقرة واحدة على الفأرة. من حيث المبدأ ، يمكن اعتبار وضع العلامات في نص البرنامج على نطاق أوسع: يمكن أن يكون عنوان URL وموقعًا آخر في ملف آخر للنص المصدر وصورة وملفًا خارجيًا به وثائق.
من السهل تخيل وجود صلة خلفية. دعنا نقول أن الوثائق تذكر فئة من الكود المصدري للبرنامج أو حتى كتلة معينة من الكود. في هذه الحالة ، سيكون من الجيد أيضًا توفير انتقال سريع إلى الجزء المطلوب من الشفرة.
نحن بحاجة إلى النظر في سيناريو آخر مهم. لنفترض أنه أثناء التطوير كانت هناك رغبة في إنشاء ملف وثائق خارجي. من المرغوب فيه إلى حد كبير أن يتم حل السؤال التنظيمي - أين يتم تخزينه ، وما الذي يجب أن نسميه ، وكيفية وضع رابط للوثائق - بشكل تلقائي قدر الإمكان حتى لا يكون هناك حاجز غير ضروري يمكن أن يخنق الدافع الصالح لإنشاء الوثائق.
مناقشة منفصلة تستحق مسألة تنسيق ملفات الوثائق. في الآونة الأخيرة ، اكتسب
تخفيض السعر شعبية ، على الرغم من الانتقادات لها (على سبيل المثال ،
هنا ). قل أن github يعرض وثائق تخفيض السعر تلقائيًا عند إدخال صفحة المشروع ، وهي ملائمة جدًا. في هذه الحالة ، تحتاج إلى اتباع اتفاق بسيط وبسيط للغاية على تسمية الملف وموقعه. أدوات العمل مع تخفيض السعر هي أيضا وفيرة ، لذلك هذا الشكل هو مرشح جيد.
التنفيذ في Codimension IDE
إلى جانب النص ، يدعم
Codimension IDE التمثيل الرسومي للرمز. يدعم IDE أيضًا لغة الترميز. لذلك ، فإن مهمة إضافة عنصر رسومي جديد لعرض ارتباطات المستندات بسيطة للغاية.
للبدء ، نقوم بصياغة متطلبات الوظيفة الجديدة في نموذج مضغوط:
- دعم تنسيق تخفيض السعر مع العرض الفوري (عرض وتحرير)
- في التمثيل الرسومي للرمز ، دعم عنصر جديد للوثائق باستخدام لغة ترميز CML
- يجب أن يعمل العنصر الرسومي للوثائق في ثلاثة إصدارات: رابط إلى مكان آخر فقط ؛ مرساة فقط للروابط من أماكن أخرى ؛ وربط ومرساة
- يمكن أن يكون الرابط هو عنوان URL أو يشير إلى ملف (ربما برقم سطر أو رقم ربط) يمكن IDE عرضه
- في تخفيض السعر دعم مخططات UML النباتية
- دعم الإنشاء السريع لملفات التوثيق والروابط الجديدة للعرض الرسومي للرمز
- حافظ على نقطة بدء وثائق التوثيق لمشروع ما ، على غرار كيفية قيام github بذلك
تخفيض السعر وتقديم
يستخدم
Codimension IDE qutepart كعنصر من مكونات محرر النصوص ، ويدعم qutepart ، بدوره ، عملية تخفيض السعر: تم تمييز بناء الجملة بالفعل. للتجسيد التلقائي ، يمكنك استخدام نفس الأسلوب المستخدم في ملفات python. المجال الرئيسي ينقسم إلى قسمين. على اليسار نص تخفيض ، وعلى اليمين يتم عرض:
تحرير تخفيض السعر باستخدام التقديم التلقائيالتقديم ، بالطبع ، يتم تلقائيا. يحدد IDE وقفة في تحرير النص ويقوم بتحديث العرض إذا لزم الأمر. بالنسبة إلى طريقة تخفيض السعر ، يتم إيقاف الجانب الأيسر مع محرر نصوص.
كان من المناسب استخدام المكتبة
الخاطئة للتقديم ، مما يسمح لك بتحويل النص بسرعة إلى HTML. يتم إرسال HTML جاهز إلى مكون QT للعرض. أثبتت مكتبة الخطأ أيضًا مرونة كافية لإضافة التعرف على أوصاف الرسم التخطيطي لـ plantUML. تتم إضافة المخطط ككتلة من التعليمات البرمجية مع اللغة المقابلة ، على سبيل المثال:
التعرف على مخطط PlantUMLplantUML يدعم أنواع مختلفة من الرسوم البيانية. بالنسبة إلى
Codimension ، يكون وصف المخطط شفافًا ، أي أنه لا يتم تحليله ، ولكن يتم نقل plantUML كما هو. وفقًا لذلك ، سيتم عرض جميع الأنواع المدعومة في إطار العرض. في وقت كتابة هذا التقرير ، دعم plantUML علامات البداية / النهاية التالية لأنواع مختلفة من الرسوم البيانية:
- Startuml /enduml
- تضمين التغريدة
- تضمين التغريدة
- startmindmap /endmindmap
- startwbs / @ endwbs
- تضمين التغريدة
- Startjcckit /endjcckit
قد يحتوي ملف تخفيض السعر القابل للتحرير على العديد من المخططات ، وكذلك الصور التي تم تنزيلها من الشبكة. الموقف المتكرر هو عندما يتغير النص قليلاً ، وتبقى موارد الرسوم دون تغيير. من أجل عدم ضخ نفس الشيء في كل مرة وعدم إعادة إنشاء المخططات ، كان من الضروري تطبيق ذاكرة تخزين مؤقت من الموارد المماثلة.
من مكتبة QT ، يتم استخدام مكون QTextBrowser الذي يدعم HTML. لسوء الحظ ، فإن لهجة HTML المدعومة محدودة ، وبالتالي فإن النتيجة النهائية يكاد يكون من المستحيل جعلها مثالية. ربما يمكن إصلاح هذا العيب في المستقبل.
كان التدخل مطلوبًا أيضًا من خلال معالجة نقرات الماوس على الروابط. قد يظهر بعض ما يلي في الرابط:
- مورد خارجي (يبدأ بـ http: // أو https: //)
- ملف بمسار نسبي من جذر المشروع أو من الملف الحالي (مناسب عند نقل دليل المشروع حول نظام الملفات)
- ملف ج المسار المطلق
وإذا كان ملفًا ، فيمكنك تحديد (العنصر الاختياري) إما معرف المرساة في هذا الملف ، أو رقم السطر. في كلتا الحالتين ، يتم استخدام معلومات إضافية لتمرير الملف إلى الموقع المطلوب.
عنصر الرسم
من المنطقي إدخال عنصر رسومي باستخدام تعليق CML جديد ، على غرار الطريقة التي تم بها بالفعل ، على سبيل المثال ، للمجموعات. يدعم CML السمات ، وهو أمر مطلوب أيضًا لعنصر الرسوم الجديد.
يشبه ارتباط الوثائق في بعض الأحيان التعليق - فهو ليس سطرًا قابلاً للتنفيذ من البرنامج ، ولكنه يوفر معلومات إضافية حول بعض السياق.
يتعرف Codimension IDE على عدة أنواع من التعليقات: مستقلة
وقيادية وجانبية. بالنسبة للوثائق ، يبدو من الحكمة الحفاظ على العناصر الرسومية المستقلة والرائدة بنفس طريقة التعليقات. هناك خلط بين العنصر الجانبي للتوثيق. النقطة المهمة هي كيف يتم تقديم التعليقات الجانبية لكتلة متعددة الأسطر من التعليمات البرمجية. يتم رسم مستطيل على يمين الكتلة ، يغطي جميع أسطر التعليق الجانبي مع دعم لمطابقة أرقام الأسطر. وماذا تفعل إذا كان مستند CML التقى في منتصف التعليق الجانبي غير واضح تمامًا. من ناحية أخرى ، لا يزال يؤدي الارتباط إلى مكان آخر ، لذلك يبدو أن دعم مستندات CML الجانبية زائدة عن الحاجة - سياق سطر معين في كتلة التعليمات البرمجية ضيق للغاية. يبدو أيضًا أن دعم مستندات CML الجانبية للوظائف والفئات ضروري. لذلك ، في هذه المرحلة ، سيتم تنفيذ مستندات CML المستقلة والرائدة فقط. تجدر الإشارة إلى أنه إذا كانت هناك حاجة معقولة في المستقبل لدعم مستندات CML الجانبية وفكرة جيدة عن كيفية عرضها ، يمكن إضافة هذه الوظيفة.
دعنا نناقش ما يجب عرضه في عنصر بياني. من الواضح أنك تحتاج إلى نص للعنصر. تم تعيين النص بواسطة المطور ويخبرك بما يشير إليه الرابط. وقد ذكرنا سابقًا أنه من المستحسن توفير انتقال إلى الوثائق بنقرة واحدة. نص العنصر الرسومي غير مناسب ، لأنه يجب احترام الاستمرارية بين سلوك العناصر الأخرى - بالنقر فوق الماوس ، يتم تحديد عنصر الرسم. ومع ذلك ، فإن حل المشكلة بسيط: يمكنك إضافة رمز ، على سبيل المثال ، إلى يسار النص ، والنقر فوق الرمز سيؤدي إلى الانتقال.
أصبحت الآن قائمة السمات الخاصة بتعليق مستند CML واضحة:
- رابط - رابط إلى مكان آخر
- مرساة - معرف مرساة للروابط من أماكن أخرى
- العنوان - النص الذي سيتم عرضه في عنصر الرسوم
- bg، fg، border - الألوان الفردية للعنصر ، إذا كان يحتاج إلى تسليط الضوء بطريقة خاصة
يجب أن يكون هناك رابط وواحد من السمتين على الأقل. بدونها ، فإن تعليق مستند CML هذا ليس له معنى كبير. سمات أخرى اختيارية. قد لا يكون النص مطلقًا ، وقد تكون الألوان قياسية.
فيما يلي مثال على الكود باستخدام مستند CML وتمثيله الرسومي:
التعليقات المستقلة والرائدة لوثيقة CMLالفرق بين العناصر الأولية والعناصر المستقلة هو فقط حيث يؤدي الموصل: إما إلى كتلة محددة أو إلى موصل بين الكتل.
عندما يكون مؤشر الماوس فوق الرمز ، ويتضمن العنصر سمة ارتباط ، يتغير شكل المؤشر ، مما يشير إلى أنه سيتم إجراء نقرة.
يدعم عنصر الرسوم أيضًا قائمة السياق. يتوفر خيار لعرض أو تحرير سمات العنصر ، بما في ذلك الألوان ، وخيار حذف عنصر.
العناصر الرسومية الأخرى
جميع العناصر الأخرى تقريبًا في التمثيل الرسومي للرمز قد تحتوي على وثائق (الاستثناءات ، على سبيل المثال ، هي تعليقات و docstrings). لذلك ، لديهم طريقة لإنشاء عنصر وثائق من خلال قائمة السياق.
قائمة السياق للعمل مع الوثائقهناك خياران فقط. أول "إضافة / تحرير doc link / anchor ..." يؤدي إلى مربع حوار مشروط لإدخال سمات الارتباط والمرساة والعنوان يدويًا. هنا ، يتمتع المطور بحرية كاملة في مكان إرسال الرابط ، ومكان وضع الملف ، إلخ.
الخيار الثاني هو أكثر إثارة للاهتمام. اسم العنصر طويل ، بسبب الإجراءات المنجزة: "إنشاء ملف مستند ، إضافة رابط وفتح للتحرير". يتم تنفيذ جميع الإجراءات تلقائيًا دون أي إدخال ، مما يسمح لك بحل المشكلة التنظيمية بسرعة:
- يتم اتخاذ قرار بشأن الملف الذي توجد به الوثائق (سننظر أدناه)
- في النص المصدر ، أضف
# cml 1 doc ... ، مما يشير إلى ملف الوثائق وله المرساة والنص الذي تم إنشاؤه. يتم إنشاء مرساة كـ doc <رقم عشوائي>. النص الثابت: انظر الوثائق - إذا كان ملف الوثائق موجودًا بالفعل ، فسيتم فتحه للتحرير في علامة تبويب جديدة
- إذا لم يكن ملف الوثائق موجودًا ، فسيتم إنشاؤه وفتحه للتحرير في علامة تبويب جديدة ، وتتم إضافة مساعدة مختصرة إلى المخزن المؤقت للتحرير ، بما في ذلك كيفية الرجوع إلى تعليق
# cml 1 doc ... المدرج حديثًا.
يعتمد قرار الملف على ما إذا كان المشروع قد تم تحميله. إذا تم تحميله ، فسيتم إنشاء الدليل الفرعي للمستند في جذر المشروع ثم المسار النسبي من جذر المشروع إلى الملف النصي المصدر. يتم تشكيل اسم الملف عن طريق استبدال الامتداد بـ .md. على سبيل المثال ، إذا كان المشروع موجودًا في
/home/me/myProject
وتضاف الوثائق لملف المشروع
/home/me/myProject/src/utils.py
سيتم إنشاء ملف وثائق
/home/me/myProject/doc/src/utils.md
وبالتالي ، فإن هيكل وثائق الكود المصدري يكرر بنية الكود المصدري ، وحتى إلقاء نظرة سريعة على الدليل الفرعي للمستند في المشروع سيكون كافيا للتنقل بسهولة. يبدو المخطط معقولًا للسلوك الافتراضي ، مما يساعد على تسريع العمل مع الوثائق.
إذا لم يتم تحميل المشروع ، فسيتم إنشاء الدليل الفرعي للمستند بجوار الملف ، وفيه يتم استبدال الملف بالملحق .md. مثل هذا السيناريو ، ومع ذلك ، يبدو من غير المرجح. إذا كنا نتحدث عن الوثائق ، فمن المؤكد أنه عمل في مشروع ، وليس في ملف منفصل.
بالطبع ، في أي وقت يمكنك تغيير العناصر التي تم إنشاؤها تلقائيًا إما عن طريق تحرير
# cml 1 doc ... في محرر نصوص أو في مربع حوار حول تمثيل رسومي.
وثائق المشروع نقطة الانطلاق
لماذا أحتاج إلى نقطة بداية وثائق؟ في رأيي ، يمكن أن يسهل عملية إدخال المشروع لأولئك الذين فتحه أولاً. على سبيل المثال ، في حالة توسيع تكوين فريق التطوير ، أو لمستخدمي المشروع. تخيل أن المشروع يحتوي على وثائق ويتكون من عدد كبير من الملفات. من أين تبدأ؟ كيف يتم تنظيم الوثائق؟ بدلاً من المضاربة ثم التحقق منها ، سيكون من الملائم الحصول على إشارة صريحة لنقطة الدخول الموصى بها.
يمكنك هنا توسيع نهج github قليلاً حتى يعمل كل من الخيار الافتراضي ومؤسسة التوثيق المحددة. إذا لم يقل أي شيء ، فسوف نبحث عن ملف README.md في جذر المشروع. ويمكن توسيع خصائص المشروع مع حقل آخر ، مما يشير إلى ملف معين من نقطة بداية الوثائق.
هناك خياران لفتح وثائق المشروع. تمت إضافة زر مع رمز تخفيض السعر إلى شريط الأدوات في نافذة IDE الرئيسية. عند النقر فوقها ، سيتم فتح ملف الوثائق في وضع العرض ، إذا كان ذلك متاحًا. إذا لم يكن هناك ملف ، فسيتم عرض موقع ملف الوثائق وسيتم فتح علامة تبويب جديدة في وضع التحرير مع النص - كعب. الخيار الثاني هو رابط لصفحة الترحيب في
Codimension ، والتي يتم عرضها عند عدم وجود علامة تبويب مفتوحة أخرى. سيتضمن النص المصاحب كلمات حول وثائق المشروع ورابطًا إذا تم العثور على الوثائق. هذه هي صفحة الترحيب التي سيشاهدها المستخدم الذي فتح المشروع لأول مرة.
اختبار في الممارسة
تم اختبار الوظيفة الموضحة أعلاه على القطط ، أي في مشروع
Codimension IDE نفسه . الآن تتضمن حزمة التثبيت الوثائق المعدة في تنسيق تخفيض السعر. لا يمكن اعتبار اختبار الأداء هذا مكتمل تمامًا ، حيث تم إعداد الوثائق للمستخدم النهائي ، وليس عن طريق الكود. ومع ذلك ، فإن الانطباع العام الذي اتضح أنه مقبول تمامًا.
أسئلة مفتوحة
هل أحتاج إلى دعم لعناصر مستند CML الجانبية؟ إذا كانت الإجابة بنعم ، فكيف رسمها ، على سبيل المثال ، لمثل هذه الحالة:
a = 10
يمكن للمرء التعرف على أوصاف مخطط plantUML مباشرة في خطوط الوثائق. إذا تم هذا الدعم ، فكيف لعرض هذه الرسوم البيانية على التمثيل البياني للرمز؟
لتسهيل إنشاء المخططات plantUML ، يمكن إضافة وظائف مع هذا السيناريو:
- يقوم المستخدم بالنقر بزر الماوس الأيمن فوق الفصل في التمثيل البياني للرمز أو في أي نافذة أخرى (قائمة فئات المشروع ، محتويات الملف المهيكلة)
- في قائمة السياق ، حدد عنصرًا لإنشاء وصف فئة بتنسيق plantUML
- يتم حفظ الوصف الذي تم إنشاؤه في مخزن مؤقت للنص.
- يقوم المستخدم بإدراج النص في مستند تخفيض السعر وتعديله إذا لزم الأمر
حيوية مثل هذا السيناريو هي موضع تساؤل ، على الرغم من أنها تافهة لتنفيذها.
إذا كان لديك أي أفكار ، يرجى مشاركتها في التعليقات.