مستندات كرمز. الجزء 1: أتمتة التحديث

في المشروعات الكبيرة ، التي تتكون من عشرات ومئات من الخدمات التفاعلية ، أصبح نهج التوثيق كرمز - مستندات كرمز - إلزاميًا بشكل متزايد.

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

مجموعة أدوات

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

كلغة ترميز نصية ، قررنا استخدام النص reStructuredText الأكثر عالمية. بالإضافة إلى عدد كبير من التوجيهات التي توفر جميع الوظائف الأساسية لهيكلة النص ، تدعم هذه اللغة التنسيقات النهائية الرئيسية ، بما في ذلك HTML المطلوب لمشروعنا.

يتم تحويل الملفات من .rst إلى .html باستخدام منشئ وثائق Sphinx . يتيح لك إنشاء مواقع ثابتة يمكنك من خلالها إنشاء سماتك الخاصة أو استخدام السمات الجاهزة. يستخدم مشروعنا موضوعين جاهزين - موضوع ستانفورد وموضوع التمهيد . يحتوي الثاني على مواضيع فرعية تسمح لك بتعيين أنظمة ألوان مختلفة لعناصر الواجهة الرئيسية.

للوصول المريح والسريع إلى الإصدار الحالي من الوثائق ، نستخدم موقعًا ثابتًا يستضيفه جهاز افتراضي يمكن الوصول إليه من شبكة المنطقة المحلية لفريق التطوير.

يتم تخزين الملفات المصدر للمشروع في مستودع Bitbucket ، ولا يتم إنشاء الموقع إلا من الملفات الموجودة في الفرع الرئيسي. لا يمكن تحديث البيانات فيه إلا من خلال طلب السحب ، والذي يسمح لك بالتحقق من جميع الأقسام الجديدة للوثائق قبل نشرها في المجال العام.

نظرًا لأن استكمال قسم جديد من الوثائق وإرساله إلى الموقع ، من الضروري التحقق من محتوياته ، والمفتاح في السلسلة بأكملها هو عملية بناء الموقع وتحديث البيانات على المضيف. يجب تكرار هذا الإجراء في كل مرة بعد دمج طلب السحب مع التحديث مع الفرع الرئيسي للمشروع.

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

1. إضافة عقدة جديدة إلى جنكينز
2. وصف Jenkinsfile
3. جينكينز وبيتبوكيت التكامل

إضافة عقدة جديدة إلى جنكينز

لإنشاء وتحديث الوثائق على الموقع ، يجب عليك تسجيل جهاز تم إعداده مقدمًا كوكيل Jenkins لهذا الغرض.

إعداد الجهاز

وفقًا لمتطلبات Jenkins ، يجب أن يكون كل المكونات المدرجة في النظام ، بما في ذلك الجهاز الرئيسي وجميع عقد الوكيل المسجل ، مثبتة على JDK أو JRE. في حالتنا ، سيتم استخدام JDK 8 ، والذي يكفي لتثبيت الأمر لتشغيله:

sudo apt-get -y install java-1.8.0-openjdk git 

سيقوم الجهاز الرئيسي بالاتصال بالوكيل لتنفيذ المهام المعينة عليه. للقيام بذلك ، تحتاج إلى إنشاء مستخدم على الوكيل الذي سيتم بموجبه تنفيذ جميع العمليات ، وسيتم تخزين جميع الملفات التي أنشأتها جينكينز في المجلد الرئيسي. على أنظمة Linux ، فقط قم بتشغيل الأمر:

 sudo adduser jenkins \--shell /bin/bash su jenkins 

لإقامة اتصال بين الجهاز الرئيسي والوكيل ، يجب عليك تكوين SSH وإضافة مفاتيح الترخيص اللازمة. سنقوم بإنشاء المفاتيح على الوكيل ، وبعد ذلك سنضيف المفتاح العمومي إلى ملف Author_keys لمستخدم jenkins .

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

 docker run hello-world 

لكي لا تضطر إلى تشغيل أوامر Docker نيابة عن المستخدم الخارق (sudo) ، يكفي إضافة مجموعة عامل إرساء المستخدم التي تم إنشاؤها في مرحلة التثبيت ، والتي سيتم تنفيذ الأوامر بالنيابة عنها.

 sudo usermod -aG docker $USER 

جينكينز تكوين عقدة جديدة

نظرًا لأن الاتصال بالعامل يتطلب تفويضًا ، يجب عليك إضافة بيانات الاعتماد المناسبة في إعدادات جينكينز. يتم توفير إرشادات مفصلة حول كيفية القيام بذلك على أجهزة Windows في وثائق Jenkins الرسمية .

هام: المعرف المحدد في قسم تكوين جينكينز -> إدارة بيئات البناء -> اسم العقدة -> التكوين في المعلمة علامات يتم استخدامه في Jenkinsfile للإشارة إلى العامل الذي سيتم تنفيذ جميع العمليات عليه.

وصف Jenkinsfile

يحتوي جذر مستودع المشروع على Jenkinsfile ، والذي يحتوي على تعليمات من أجل:

• تحضير بيئة البناء وتثبيت التبعيات
• بناء موقع باستخدام Sphinx
• تحديث معلومات المضيف.

يتم تعيين الإرشادات باستخدام توجيهات خاصة ، سنقوم بتطبيقها لمزيد من النظر في مثال الملف المستخدم في المشروع.

إشارة وكيل

في بداية Jenkinsfile ، حدد ملصق الوكيل في Jenkins ، والذي سيتم تنفيذ جميع العمليات عليه. للقيام بذلك ، استخدم توجيه الوكيل :

 agent { label '-' } 

إعداد البيئة

لتنفيذ أمر بناء موقع أبو الهول ، تحتاج إلى تعيين متغيرات البيئة التي سيتم تخزين مسارات البيانات الفعلية فيها. أيضًا ، لتحديث المعلومات على المضيف ، يجب عليك تحديد المسارات التي يتم فيها تخزين بيانات الموقع مع الوثائق مقدمًا. يسمح لك توجيه البيئة بتعيين هذه القيم إلى المتغيرات:

 environment { SPHINX_DIR = '.' //,    Sphinx BUILD_DIR = 'project_home_built' //    SOURCE_DIR = 'project_home_source' //   .rst  .md  DEPLOY_HOST = 'username@127.1.1.0:/var/www/html/' //@IP__:__ } 

الإجراءات الرئيسية

وترد التعليمات الرئيسية التي سيتم تنفيذها في Jenkinsfile في توجيه المراحل ، والذي يتكون من الخطوات المختلفة الموضحة في توجيهات المرحلة . مثال بسيط على خط CI ثلاثي المراحل:

 pipeline { agent any stages { stage('Build') { steps { echo 'Building..' } } stage('Test') { steps { echo 'Testing..' } } stage('Deploy') { steps { echo 'Deploying....' } } } } 

قم بتشغيل حاوية Docker وتثبيت التبعيات

أولاً ، قم بتشغيل حاوية Docker مع صورة بيثون النهائية : 3.7 . للقيام بذلك ، استخدم الأمر docker run مع - rm و -i الإشارات. ثم قم بالتتابع بما يلي:

• تثبيت بيثون virtualenv .
• إنشاء وتفعيل بيئة افتراضية جديدة ؛
• تثبيت فيه جميع التبعيات اللازمة المدرجة في الملف
  requirements.txt ، التي يتم تخزينها في جذر مستودع المشروع.

 stage('Install Dependencies') { steps { sh ''' docker run --rm -i python:3.7 python3 -m pip install --user --upgrade pip python3 -m pip install --user virtualenv python3 -m virtualenv pyenv . pyenv/bin/activate pip install -r \${SPHINX\_DIR}/requirements.txt ''' } } 

بناء موقع مع الوثائق

الآن دعونا نبني موقعًا. للقيام بذلك ، قم بتشغيل الأمر sphinx-build بالأعلام التالية:

-q : سجل التحذيرات والأخطاء فقط ؛
-w : اكتب -w للملف المحدد بعد العلم ؛
-b : اسم منشئ الموقع ؛
-d : تحديد الدليل لتخزين الملفات المخزنة مؤقتًا - المخللات المذهبية.

قبل بدء التجميع ، باستخدام rm -rf احذف تجميع الموقع السابق rm -rf . في حالة حدوث خطأ في إحدى المراحل ، سيظهر سجل تنفيذ أبو الهول في وحدة التحكم Jenkins .

 stage('Build') { steps { // clear out old files sh 'rm -rf ${BUILD_DIR}' sh 'rm -f ${SPHINX_DIR}/sphinx-build.log' sh ''' ${WORKSPACE}/pyenv/bin/sphinx-build -q -w ${SPHINX_DIR}/sphinx-build.log \ -b html \ -d ${BUILD_DIR}/doctrees ${SOURCE\_DIR} ${BUILD\_DIR} ''' } post { failure { sh 'cat ${SPHINX_DIR}sphinx-build.log' } } } 

تحديث موقع المضيف

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

كأداة التزامن ، نستخدم الأداة المساعدة rsync . لكي يعمل بشكل صحيح ، من الضروري تكوين اتصال SSH بين حاوية Docker ، حيث كان الموقع مع الوثائق ، والمضيف.

لتكوين اتصال SSH باستخدام Jenkinsfile ، يجب تثبيت الإضافات التالية في Jenkins :

1. SSH Agent Plugin - يسمح لك باستخدام الخطوة sshagent في البرامج النصية لتوفير بيانات اعتماد اسم المستخدم / المفتاح .
2. SSH مؤهلات اعتماد المكون الإضافي - يسمح لك بحفظ بيانات اعتماد اسم المستخدم / المفتاح في إعدادات جينكينز .

بعد تثبيت المكونات الإضافية ، يجب عليك تحديد بيانات الاعتماد الحالية للاتصال بالمضيف عن طريق ملء النموذج في قسم بيانات الاعتماد :

• المعرف : المعرف الذي سيتم استخدامه في Jenkinsfile في الخطوة sshagent للإشارة إلى بيانات اعتماد محددة ( docs-deployer ) ؛
• اسم المستخدم : اسم المستخدم الذي سيتم بموجبه تنفيذ عمليات تحديث بيانات الموقع (يجب أن يكون لدى المستخدم حق وصول للكتابة إلى المجلد /var/html للمضيف) ؛
• المفتاح الخاص : مفتاح خاص للوصول إلى المضيف ؛
• عبارة المرور : كلمة مرور للمفتاح ، إذا تم تعيينها في مرحلة التوليد.

أدناه هو رمز البرنامج النصي الذي يتصل عبر SSH وتحديث المعلومات على المضيف باستخدام متغيرات النظام المحددة في مرحلة إعداد البيئة مع المسارات إلى البيانات اللازمة. تتم كتابة نتيجة الأمر rsync إلى السجل ، والذي سيتم عرضه في وحدة تحكم Jenkins في حالة حدوث أخطاء التزامن.

 stage('Deploy') { steps { sshagent(credentials: ['docs-deployer']) { sh ''' #!/bin/bash rm -f ${SPHINX_DIR}/rsync.log RSYNCOPT=(-aze 'ssh -o StrictHostKeyChecking=no') rsync "${RSYNCOPT[@]}" \ --delete \ ${BUILD_DIR_CI} ${DEPLOY_HOST}/ ''' } } post { failure { sh 'cat ${SPHINX_DIR}/rsync.log' } } } 

جينكينز وبيتبوكيت التكامل

هناك العديد من الطرق لتنظيم تفاعل Jenkins و Bitbucket ، ولكن في مشروعنا قررنا استخدام الأداة المساعدة Parameterized Builds لـ Jenkins . تحتوي الوثائق الرسمية على إرشادات مفصلة لتثبيت المكون الإضافي ، وكذلك الإعدادات التي يجب تحديدها لكلا النظامين. للعمل مع هذا البرنامج المساعد ، تحتاج إلى إنشاء مستخدم Jenkins وإنشاء رمز مميز خاص به سيسمح لهذا المستخدم بتسجيل الدخول إلى النظام.

إنشاء مستخدم ورمز API

لإنشاء مستخدم جديد في جينكينز ، انتقل إلى إعدادات جينكينز -> إدارة المستخدم -> إنشاء مستخدم ، وملء جميع بيانات الاعتماد اللازمة في النموذج.

آلية المصادقة التي تسمح للبرامج النصية أو التطبيقات التابعة لجهات أخرى باستخدام Jenkins API دون نقل كلمة مرور المستخدم فعليًا هي رمز مميز لواجهة برمجة التطبيقات يمكن إنشاؤه لكل مستخدم Jenkins . للقيام بذلك:

• تسجيل الدخول إلى وحدة التحكم بالإدارة باستخدام تفاصيل المستخدم التي تم إنشاؤها مسبقًا ؛
• انتقل إلى تكوين جنكينز -> إدارة المستخدم ؛
• انقر على أيقونة الترس على يمين اسم المستخدم الذي أذن به في النظام ؛
• ابحث عن واجهة برمجة تطبيقات Token في قائمة المعلمات وانقر على زر إضافة رمز جديد ؛
• في الحقل الذي يظهر ، حدد معرف رمز واجهة برمجة التطبيقات وانقر فوق الزر " إنشاء" ؛
• بعد المطالبة على الشاشة ، انسخ وحفظ الرمز المميز API الذي تم إنشاؤه.

الآن في إعدادات خادم Bitbucket ، يمكنك تحديد المستخدم الافتراضي للاتصال بـ Jenkins .

استنتاج

إذا كانت العملية تتكون في وقت سابق من عدة خطوات:

• قم بتنزيل التحديث إلى المستودع
• انتظر تأكيد صحة ؛
• وضع موقع على شبكة الانترنت مع الوثائق ؛
• تحديث المعلومات على المضيف ؛

الآن فقط انقر فوق زر واحد دمج في Bitbucket. إذا لم يكن مطلوبًا بعد التحقق من إجراء التغييرات على الملفات المصدر ، يتم تحديث الإصدار الحالي من الوثائق فور تأكيد صحة البيانات.

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

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

شكرا لأولئك الذين قرأوا هذا للانتباه ، سنواصل قريبًا مشاركة تفاصيل إنشاء الوثائق في مشروعنا!