لفترة طويلة ، كان العديد من الأشخاص يستخدمون بنشاط أو يتطلعون إلى نموذج تخزين ونشر
الوثائق كرمز ، وهذا يعني تطبيق نفس القواعد والأدوات والإجراءات على الوثائق الخاصة برمز البرنامج ، على سبيل المثال ، تخزينه في المستودع ، إجراء الاختبارات ، تجميع وإصدار في CI / CD. يتيح لك هذا النهج الحفاظ على الوثائق محدّثة من خلال الكود والنسخة وتتبع التغييرات باستخدام أدوات التطوير المألوفة.
ومع ذلك ، في نفس الوقت ، كان لدى العديد من الشركات أيضًا الويكي لسنوات ، والتي تتمتع فيها الفرق والموظفون الآخرون ، مثل مديري المشاريع ، بالوصول إلى الوثائق. ماذا لو كنت ترغب في نقل التخزين والنشر إلى عرض واحد ، إلى جانب قواعد نشر HTML في Confluence؟ في هذه المقالة ، سأقدم نظرة عامة على الحلول الخاصة بمهمة نشر المستندات من مستودع التخزين في Confluence.
أستخدم بنشاط أحد الحلول لفترة طويلة في فريق تطوير الواجهة (حزمة RST-Sphinx + sphinxcontribbuilder) ، وسأقدم الحلول الأخرى كبديل ، وسأقول على الفور أنني لم أجربها على أرض الواقع ، لقد قمت فقط بدراسة التكوين.
Sphinx doc + sphinxcontribbuilder
Sphinx (يجب عدم الخلط بينه وبين فهرس البحث الذي يحمل نفس الاسم) هو منشئ وثائق مكتوب بلغة Python ويستخدمه المجتمع بفعالية ؛ إنه يعمل جيدًا في بيئات أخرى أيضًا.
لن نتحدث عن إعداده بالتفصيل ، سأحفظ فقط أنه من خارج الصندوق يمكنه إنشاء HTML ثابت ، ورجل ، وملف pdf ، وعدد من التنسيقات الأخرى ، وللتجميع والنشر الصحيحين في المستودع ، يجب أن يكون هناك فهرسة. الملفات الأولى (تخطيط الصفحة الرئيسية) ، conf.py (ملف التكوين) و Makefile (ملف يصف عملية إنشاء التنسيقات ، وهنا من الممكن تمامًا تخييطه في عامل ميناء وتشغيل الأمر
sphinx-build هناك).
من خارج منطقة الجزاء ، يمكن لـ Sphinx إنشاء أحواض من تصميم RestrusturedText * خفيف الوزن ، لكننا أضفنا القدرة على الكتابة إلى Markdown (نكهة CommonMark) لهؤلاء المطورين الأكثر راحة (امتداد
m2r الذي يحول MD إلى RST ساعدنا) .
لقد قمنا بالفعل بإعداد البيئة بأكملها لـ Sphinx ، وتم تجميع مجموعة الوثائق إلى مرحلة منفصلة في
خط أنابيب Jenkins ، لذلك
تابعنا واستخدمنا امتداد
sphinxcontrib.confluencebuilder ، الذي يمكنه جمع الأرصفة بالتنسيق الأصلي لـ Confluence ثم نشرها. التقاء في هذه الحالة هو أحد تنسيقات إخراج الوثائق ، إلى جانب HTML.
لكي يعمل هذا ، تحتاج إلى توصيل الامتدادات في conf.py ، فيما يلي جزء التهيئة.
extensions = [ 'sphinxcontrib.confluencebuilder', 'm2r' ] templates_path = ['_templates'] source_suffix = ['.rst', '.md'] master_doc = 'index' exclude_patterns = [ u'docs/warning-plate.rst', u'FEATURE.md', u'CHANGELOG.md', u'builder/README.md' ]
ثم قم بتكوين الامتداد ، به مجموعة من الإعدادات:
confluence_publish = True
النقطة المهمة هي أنه حتى إذا لم يتم تحديد الصفحة (المصدر في .rst) في toc ولم تتم إضافتها إلى exclude_patterns ، فسيظل نشرها ، ولكن خارج التسلسل الهرمي.
تتوافق أسماء الصفحات الموجودة في Confluence مع العنوان الأول للصفحة ، على سبيل المثال ، إذا كان لديك رأس Example في ملف example.rst ، مسطر بعلامات متساوية ، فسيصبح اسم الصفحة في Confluence.
قاعدة النظافة ، والتي هي واضحة إلى حد ما ، ولكن لا يزال: إنشاء روبوت مع بيانات التخويل التي ستقوم بنشر المستندات الخاصة بها ، ويمكن نقلها كمتغيرات البيئة في إنشاء عامل ميناء ، المستخدمة في خطوط الأنابيب.
بالطبع ، هناك مطبات. أولاً ، ليس كل بناء جملة RST مدعومًا للنشر في Confluence (╯ ° □ °） ╯︵ ┻━┻) ، فهذا غير مريح إذا كنت ترغب في تجميع HTML و Confluence من مصدر واحد. الحاوية ، توجيهات القائمة ليست مدعومة ، وجميع سمات التوجيه تقريبًا ، على سبيل المثال ، تسليط الضوء على الأسطر في رمز الكتلة ، والترقيم في جدول المحتويات ، ومحاذاة وعرض جدول القائمة.
قائمة ما يدعم هو جيد جدا .
من الأشياء الممتعة ، بما في ذلك المدعومة ، هذا يتيح لك إعادة استخدام أجزاء من المحتوى بين المستندات المختلفة ، و autocod لتجميع الوثائق من التعليمات البرمجية ، والرياضيات للصيغ الرياضية ، ورسم التذاكر والفلاتر من jira (لهذا ستحتاج أيضًا إلى تسجيل خادم Jira في التهيئة) ، والرؤوس المرقمة والكثير آخر ، حرفيا في 3 يناير ألقى
تحديث كبير .
بالمناسبة ، ظهر دعم Jira في multiconverter من Pandoc ، بدءًا من
الإصدار 2.7.3 يدعم
Pandoc ترميز الويكي المقابل.
بالنسبة إلى وحدات الماكرو وعناصر التقاء غير المدعومة ، يوجد اختراق قذر. يحتوي RST على توجيه
... raw :: ، ولديه سمة التقاء ، فإنه يقبل ترميز conf ، إذا كنت حقًا بحاجة إلى نوع ما من الماكرو - يمكنك نسخه في وضع تحرير الصفحة في Confluence (يتوفر وضع الرمز المصدر بواسطة رمز <>) و الصق الكود "الخام" هناك. لكنني لم أعلمك هذا.
.. raw:: confluence <ac:structured-macro ac:macro-id="c38bab13-b51e-4129-85ef-737eab8a1c47" ac:name="status" ac:schema-version=^_^quot quot^_^> <ac:parameter ac:name="colour">Green</ac:parameter> <ac:parameter ac:name="title">Is used</ac:parameter> </ac:structured-macro>
والنتيجة هي كما يلي:
لماذا احتجنا إلى تهيئة المنشور من المستودع المحلي إلى صفحة الاختبار ، وليس على الفور "prod"؟ والحقيقة هي أنه عند نشر كل الصفحات يتم إعادة نشرها في كل مرة وطحن التغييرات التي أدخلت يدويا أو التعليقات في السطر (مضمنة). لذلك ، عندما يكون المستند قيد التقدم ، قررنا نشره في صفحة منفصلة ، مثل وضع dev ، لإضافة إصدارات منشورة إلى المراجعة وجمع التعليقات.
في CI ، يتم تطبيق المنشور كمرحلة منفصلة في خط أنابيب Jenkins ، داخل هذه المرحلة يتم إطلاق صورة عامل ميناء على السجل البعيد ، الذي ينفذ بناء أبو الهول مع التكوين المطلوب. من الأفضل تخطي هذه الخطوة على الفور.
pipeline { agent { label "${AGENT_LABEL}" } stage("Documentation") { steps { ansiColor('xterm') { withCredentials([usernamePassword( credentialsId: "${DOCUMENTATION_BOT}", usernameVariable: 'CONFLUENCE_USERNAME', passwordVariable: 'CONFLUENCE_PASSWORD' )]) { sh "docker-compose -p $COMPOSE_ID run sphinx-doc confluence" } }} }
داخل المسرح ،
يتم إطلاق
التقاء سفن-دوك -إصدار-فرع-الاسم-التشغيل- الواقع. Jenkinsfile ، بدوره ، يصف التبعيات والبيئة التي سيتم فيها تنفيذ الخطوة ، وهي عملية تجميع المعلومات وتحديثها في الهدف. من الاختبارات حتى الآن لا يوجد سوى اختبار بناء الجملة من .md و. rst مع doc8 و markdownlinter.
فارق بسيط آخر: في كل مرة تقوم فيها بنشر شبكة فرعية للصفحة ، يقوم Sphinx بتحديث الشجرة بأكملها ، كل صفحة. وهذا هو ، حتى لو لم يتغير المحتوى ، يتم إنشاء تغيير ، إذا كان لديك إعلامات تم تكوينها في القناة ، فسيتم انسدادها بعدد كبير من الإعلامات.
وهناك عدد قليل من الطرق
أوراق الشجر مع التقاء كخلفية
أداة توثيق أوراق الشجر مع Mkdocs والعديد من المعالجات الأولية تحت الغطاء والواجهة الخلفية في شكل التقاء. يمكنك
قراءة المزيد هنا ، ولكن باختصار ، يستخدم pandoc لتحويل md إلى HTML ، ثم نشره في Confluence. تحتاج فقط إلى تكوين الواجهة الخلفية وتثبيت pandoc في البيئة كتبعية.
الاختلافات المواتية عن الحل الأول: يمكنه استعادة التعليقات المضمّنة في نفس الأماكن التي كانت عليها قبل نشر الصفحة ، ويسمح لك بإنشاء صفحات عن طريق تعيينها في التهيئة ، وتحرير أسمائها ، وكذلك إدراج محتوى في صفحة موجودة ، لذلك تحتاج إلى تعيينها يدويًا مرساة أوراق الشجر على الصفحة في التقاء.
إنه يعمل فقط مع المصدر على تخفيض السعر.
مترو
أداة متعددة الأدوات تنشر مجموعة متنوعة من تنسيقات المصادر في التقاء ، من محرّر مستندات Google إلى Salesforce Quip و Markdown ، أيضًا.
للنشر ، تحتاج إلى وضع ملف manifest.json في المجلد الذي توجد به ملفات .md ، وحدد المجلد فيه ، والملف الذي تريد نشره ، ولكل ملف حدد معرف صفحة التقاء. سيكون عنوان الصفحة هو العنوان الأول في الملف (#). تحتوي هذه الأداة على بعض الانحرافات باستخدام ترميز Markdown ، لذلك شاهد
الأرصفة . يجب وضع المرفقات والصور في نفس المجلد ، كما تتيح لك الأداة تحديد استخدام جدول المحتويات مباشرة في التكوين.
جوهرة md2conf
Ruby gem
md2conf ، يقوم بتحويل برنامج Markdown إلى برنامج Confluence XHTML الأصلي. ثم يمكنك كتابة مهمة Rake ، والتي بدورها يمكن استدعاؤها عبر Gitlab CI / Jenkins للدفع إلى الرئيسي ، ثم سحب واجهة برمجة تطبيقات Confluence API لنشر الصفحة. من أجل عدم إحضار بيئة Ruby إليك ، قم بلف التبعيات الخاصة بهذه الأحجار الكريمة في حاوية.
يتم وصف كيفية إرسال الطلبات إلى واجهة برمجة تطبيقات Confluence
هنا .
إنه يعمل فقط مع المصدر على تخفيض السعر.
من وجدت على جيثب
في الواقع ، تم بالفعل تنفيذ عدد من هذه البرامج النصية أو أدوات cli في المجتمع ، لكنني جربت فقط مع md2conf ، كلها مقسمة إلى مجموعتين.
تلك التي تقوم فقط بتحويل التنسيقات (md، asciidoc، rst -> confluence / xhtml):أكثر هذه الأفكار التي رأيتها هوًا (https://github.com/rogerwelin/markdown2confluence-server) ، فقد كتب المؤلف على الفور Dockerfile ، الذي يثير أداة cli-tool كخادم REST ، ثم يمكنك إرسال حزمة من طلبات التحويل إليها .
وتلك التي تنفذ على الفور طلبات في Confluence API ، تحتاج فقط إلى تحديد مفتاح API في التكوين:
اختر أيًا من الخيارات (اعتمادًا على لغة الترميز والمكدس) وجمع خط الأنابيب وفقًا للمهام التي تواجهها.
ملاحظة: إذا كنت تشارك في تعليقات حلول أخرى وجدت لهذه المشكلة ، سأكون ممتنا للغاية.
وإذا كنت تريد التحدث معي أكثر حول هذه المواضيع ، تعال إلى KnowledgeConf 2020 في 18 مايو.