From 87be4c37f6a50c632eb47cbf2ae9b36a01827feb Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Wed, 3 Jul 2024 22:36:59 +0100 Subject: [PATCH 1/6] New translations index.qmd (Arabic, Saudi Arabia) --- docs/_translations/ar/index.ar.qmd | 82 ++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 docs/_translations/ar/index.ar.qmd diff --git a/docs/_translations/ar/index.ar.qmd b/docs/_translations/ar/index.ar.qmd new file mode 100644 index 00000000..0d2f1457 --- /dev/null +++ b/docs/_translations/ar/index.ar.qmd @@ -0,0 +1,82 @@ + +# Welcome to JSQuarto Documentation + +## About +JSQuarto هي أداة مصممة لتوليد وثائق مرجعية لحزمة API جافا سكريبت باستخدام Markdown و Quarto. يعمل كبديل لـ JSDoc، ويوفر نهجا أبسط وأكثر مرونة لتوثيق شفرة جافا سكريبت. + +## Purpose +الغرض من JSQuarto هو تبسيط عملية إنشاء وثائق API المرجعية لحزم جافا سكريبت. من خلال الاستفادة من Markdown و Quarto، يمكن للمطورين إنشاء وحفظ وثائق شاملة لمشاريع جافا سكريبت الخاصة بهم. + +## Inspiration +JSQuarto يستلهم من أدوات ومنهجيات التوثيق المختلفة، بما في ذلك:
+ +- [JSDoc](https://jsdoc.app/): JSDoc is a popular tool for generating API documentation from JavaScript source code.
+- [Quarto](https://quarto.org/): Quarto is a versatile document authoring and publishing tool that supports Markdown, LaTeX, and R Markdown formats.
+- [Sphinx](https://www.sphinx-doc.org/): Sphinx is a documentation generation tool widely used in the Python community.
+ +## Localization and Translation +وشركة JSQuarto ملتزمة بدعم توطين وترجمة الوثائق التي تم إنشاؤها. نحن نخطط لدمج كراودن، وهي منصة لإدارة التعريب ، لتسهيل جهود الترجمة. وهذا سيمكن المستخدمين من تقديم ملفات QMD التي تم إنشاؤها بلغات متعددة، مما يجعل الوثائق متاحة لجمهور أوسع. + +## Getting Started +#### Prerequisites + +قبل اختبار الأداة محلياً، تأكد من وجود الشروط المسبقة التالية مثبتة على النظام الخاص بك: + +- [Quarto](https://quarto.org/) +- [Babel Quarto](https://docs.ropensci.org/babelquarto/) +- Node.js and npm (Node Package Manager) + +#### التثبيت + +لاختبار الأداة محلياً، قم باتباع الخطوات التالية: + +1. Install the tool by running the command below + + “`باش + npm install -g @oscsa/jsquarto + ``` + +### Usage +Once the dependencies are installed, you can navigate to the root directory of your project and follow the steps below: + +1. لإنشاء الوثائق قم بتشغيل الأمر التالي + + “`باش + jsq doc:generate source= + ``` + + هذا سوف يستخرج تعليقات JSDoc من ملفات js و يكتبها إلى ملفات Quarto Markdown المقابلة. + + If the `source` flag is not provided, the tool will set `/source_files` as default. + + The generated `.qmd` files can be found in the `/docs` folder, you can change the output directory by providing the `output` flag. + +2. لمعاينة الوثائق التي تم إنشاؤها قيد التشغيل + + “`باش + jsq doc:preview + ``` + + سيؤدي هذا إلى إنشاء الوثائق، ومعاينة مع quarto وفتح رابط لمعاينة المستندات + +3. The generated `.qmd` files can be found in the `/docs` folder, you can change the output directory by providing the `output` flag. + + “`باش + jsq doc:generate source= output= + ``` + +4. To include tutorials in the generated documentation, provide the `tutorials` flag. + + “`باش + jsq doc:generate source= tutorials= + ``` + +For more information on how to integrate translation tools like Crowdin with JSquarto, refer to the [Crowding workflow guide](https://jsquarto.netlify.app/chapters/tutorials/how_to/workflows#doc-generation-with-crowdin-translation). + +For more details on using JSquarto and to see an example of the generated documentation, visit the [JSQuarto documentation](https://jsquarto.netlify.app/) + +## Contributing Organization +تم تطوير وصيانة JSQuarto من قبل [المجتمع العلمي المفتوح في المملكة العربية السعودية] (https://github.com/Open-Science-Community-Saudi-Arabia). وتتمثل مهمتنا في تعزيز الممارسات العلمية المفتوحة وتعزيز التعاون بين الباحثين والمطورين في المملكة العربية السعودية. + +## Feedback and Support +إذا كان لديك أي أسئلة، أو ردود فعل، أو تحتاج إلى دعم، يرجى [فتح مشكلة] (https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/issues) على GitHub أو [الانضمام إلى مجتمعنا](https://github.com/Open-Science-Community-Saudi-Arabia) للحصول على المساعدة. \ No newline at end of file From 91f8df873eeaefffa9b831abc1f856283ddf169e Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Thu, 4 Jul 2024 00:04:34 +0100 Subject: [PATCH 2/6] New translations globals.qmd (Arabic, Saudi Arabia) --- .../ar/chapters/globals/globals.ar.qmd | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/_translations/ar/chapters/globals/globals.ar.qmd b/docs/_translations/ar/chapters/globals/globals.ar.qmd index 0ecdc4f5..9591d379 100644 --- a/docs/_translations/ar/chapters/globals/globals.ar.qmd +++ b/docs/_translations/ar/chapters/globals/globals.ar.qmd @@ -19,6 +19,28 @@ +## findSubFolderWithMatchingName +`[function]` + +** المعلمات (Params):** + +| الاسم | الوصف | +| --- | --- | +| h | The path to the folder to search for the subfolder in. | + + + +## moveDirContents +`[function]` + +** المعلمات (Params):** + +| الاسم | الوصف | +| --- | --- | +| r | The directory to move files and folders from. | + + + ## mergePathsForTranslatedFiles `[function]` From bd6a03741688cb0c5a49e8bffb4e2a57359037ef Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Thu, 4 Jul 2024 00:04:35 +0100 Subject: [PATCH 3/6] New translations changelog.qmd (Arabic, Saudi Arabia) --- .../ar/chapters/tutorials/changelog.ar.qmd | 83 +++++++++++++------ 1 file changed, 58 insertions(+), 25 deletions(-) diff --git a/docs/_translations/ar/chapters/tutorials/changelog.ar.qmd b/docs/_translations/ar/chapters/tutorials/changelog.ar.qmd index ca67dad4..ac4ce7b5 100644 --- a/docs/_translations/ar/chapters/tutorials/changelog.ar.qmd +++ b/docs/_translations/ar/chapters/tutorials/changelog.ar.qmd @@ -5,34 +5,67 @@ title: Changelog title: سجل التغيير --- - -# تغيير -وسيتم توثيق جميع التغييرات الملحوظة في هذا المشروع في هذا الملف. - -التنسيق مبني على [الحفاظ على تغيير](https://keepachangelog.com/en/1.0.0/) -ويلتزم هذا المشروع بـ [النسخة السامية](https://semver.org/spec/v2.0.0.html). +وسيتم توثيق جميع التغييرات الملحوظة في هذا المشروع في هذا الملف. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines. + +## 1.0.5 (2024-06-12) +#### Bug Fixes + +* incorrect file paths while merging crowdin translations ([0196156](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/01961566ef87639cb120d6704b401473d7a7c969)) +* incorrect translations directory in default config ([cfa81fc](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/cfa81fc650b0d52ee2e1b830fa0a0d131fd7b43f)) + +## 1.0.4 (2024-06-11) +#### Features + +- `fix:all` to run all custom fixes in order ([5a52490](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/5a524906f91c201b876862039048dcc82ca4df93)) +- Add right-to-left styling for arabic docs ([99f74ef](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/99f74ef7f639dee02bc5ebfed0b4acd53ccb85d0)) +- Initialize config file in any directory ([b4b9055](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/b4b90557c4616627d4072438be6d5a5feabe5172)) +- prepareDirectoryForDocs ([93a8698](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/93a8698986bae201eae9e5224b5bb097a9fa2ca5)) +- Remove duplicate references to language in dropdown menu ([7074ea9](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/7074ea9131ed9e19a9d43ba98903206ae5f9ad4a)) +- Script to fix localized files ([cfa8c8d](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/cfa8c8d5e3b78a1fe32e60eda0fb38fc85f4e5aa)) +- Script to fix localized files ([c20baf5](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/c20baf55a86894fdd3e837adc76469d09d5ddb22)) +- Script to fix structure crowdin files after new update ([14ec202](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/14ec2020972d5471b9706d55a4c8208615004009)) +- Script to fix structure crowdin files after new update ([0a0ebec](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/0a0ebec47b0ef8146b1274a4f84ec66a5955bf31)) +- Set config in file from cli ([346866f](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/346866f886d3ee963b2edbde5c29d824ecc86d05)) +- Set project config path from cli ([3c75d04](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/3c75d04b7341f680a6666070b266134d2328478c)) +- Upate config path record for project ([a4b80d9](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/a4b80d9d93ebc1dc845d4a3ac7fa8f76fb6a610d)) + +#### Bug Fixes + +- `fix:all` for bug with language menu working in built book ([37f9f4f](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/37f9f4f2be52e393a895468653df99171af4a5ce)) +- `fix:all` for bug with language menu working in built book ([7fc0adb](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/7fc0adb181fe5a55a7ad275e33aef2866b1c0a0a)) +- all modules being categorized under default ([ef33600](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/ef336000bdc14c486d252020475019044035eb70)) +- comment util returning 'other' for all types of comments ([19b0d49](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/19b0d49ffed619bb0acf4ccc89f5f80bdb3db92f)) +- dir not found error when writing doc for global variables ([cdef7ff](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/cdef7ff6346e42188950aa765136f7d28a36304b)) +- duplicate headings in tutorials ([e50bfaa](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/e50bfaae27af411144244f7cf6088eeb2062f151)) +- getConstructName returning other ([c5b2176](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/c5b21762e60810b52ab93a74c6d0a09002273404)) +- globals section appearing twice ([5ace1d9](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/5ace1d98fdc3eaddd7ca8226957a8dd066e68cc1)) +- broken image ref in tutorial ([39044dd](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/39044ddc104680e1207ee4bb7a6c42a90eb06465)) +- issue with generating language files ([77ff687](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/77ff6874ea257d9a4b4465561f73a74b8dc0e816)) +- tutorials not taking title from tutorial config ([104c294](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/104c294df45b4a7b0c4ff376f26153a2f9e1215a)) +- modules without categories not linked to globals ([38c51cf](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/38c51cfd9c5fc9232c3d5b5f47fbb77856636a58)) +- npm scripts throwing error when extra args are passed ([c91f59f](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/c91f59f0e179aed83e6453c7a60b1dfee19eb0f9)) +- tutorials without chapter not included in quarto.yaml ([71452ce](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/71452ce397d5542b76776149476bb64d306a0230)) +- wrong code construct name in generated doc ([c939628](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/commit/c939628b69f2c575beb2e41eb3e9272ed0405ef4)) ## لم يفرج (2024-03-05) - -### الميزات: - -- استخراج مستخرجات من ملفات جافا سكريبت ([`#13`](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/pull/3)) -- إنشاء هيكل التوثيق في ملف `quarto.yml` ([`#9`](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/pull/7)) -- ربط الوثائق غير المطابقة بفئة 'Globals' ([`#21'](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/pull/21)) -- المراجع المتعلقة بكتل الكتل الكتل والموارد الخارجية ([`#22`](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/pull/22)) -- إضافة وثائق لـ JSQuarto ([`#25`](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/pull/25)) -- إضافة دروس لـ JSQuarto ([`#26`](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/pull/26)) -- إضافة 'كيفية الإرشادات' وخطوط الأوامر المخصصة ([`#30'](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/pull/30)) - - -### تم إصلاح الأخطاء: -- تحسين التنسيق لـ `params' و `thrown errors' و `returns' ([#14`](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/pull/14)) -- إزالة التركيبات البرمجية من وثائق الدالة ([`#15`](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/pull/15)) -- إصلاح عناوين الترويسة غير المتسقة من الوثائق المستخرجة ([`#17`](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/pull/17)) - - -#### المساهمون ✨ +#### Features: +- Extract docstrings from javascript files ([#13](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/pull/3)) +- Generate documentation structure in `quarto.yml` file ([#9](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/pull/7)) +- Link unmatched documents to `Globals` category ([#21](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/pull/21)) +- References for doc snippets and external resources ([#22](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/pull/22)) +- Add documentation for JSQuarto ([#25](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/pull/25)) +- Add tutorials for JSQuarto ([#26](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/pull/26)) +- Add `How to guides` and custom command line args ([#30](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/pull/30)) + +#### Bugs fixed: + +- Improve formatting for `params`, `thrown errors` and `returns` ([#14](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/pull/14)) +- Remove code constructs from function documentation ([#15](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/pull/15)) +- Fix inconsistent header titles from extracted documents ([#17](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/pull/17)) + +## Contributors ✨ +
شكرا لهؤلاء الناس الرائعين (مفتاح [emoji](https://allcontributors.org/docs/en/emoji-key)): From 112e20c121ee8c768fd7cf2aa6bbf0ebd2d38419 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Thu, 4 Jul 2024 00:04:36 +0100 Subject: [PATCH 4/6] New translations improving_documentation.qmd (Arabic, Saudi Arabia) --- .../improving_documentation.ar.qmd | 187 ++---------------- 1 file changed, 16 insertions(+), 171 deletions(-) diff --git a/docs/_translations/ar/chapters/tutorials/contributing/improving_documentation.ar.qmd b/docs/_translations/ar/chapters/tutorials/contributing/improving_documentation.ar.qmd index d29bbd19..67c86f8f 100644 --- a/docs/_translations/ar/chapters/tutorials/contributing/improving_documentation.ar.qmd +++ b/docs/_translations/ar/chapters/tutorials/contributing/improving_documentation.ar.qmd @@ -4,16 +4,24 @@ title: Improving documentation يعد التوثيق الفعال أمرًا بالغ الأهمية للحفاظ على قاعدة تعليمات برمجية واضحة ومفهومة. واحدة من الأدوات القوية لتعزيز التوثيق في الكود الخاص بك هي JSDoc. JSDoc هي لغة ترميز تسمح لك بالتعليق على التعليمات البرمجية الخاصة بك مع تعليقات منظمة، مما يمكن من التوليد التلقائي للوثائق. في هذا الدليل، سوف نستكشف استخدامات JSDoc وكيف يمكن أن يحسن توثيق مشروعك. ### Using JSDoc for Generated Documentation - +
أحد الاستخدامات الأساسية لـ JSDoc هو توليد الوثائق مباشرة من الكود الخاص بك. من خلال إضافة تعليقات JSDoc إلى الدوال والصفوف والمتغيرات الخاصة بك، يمكنك تقديم معلومات أساسية يتم استخراجها تلقائياً وتحويلها إلى وثائق شاملة. لاستخدام JSDoc لتوليد الوثائق، اتبع الخطوات التالية: 1. تعليقات الترميز: إضافة تعليقات JSDoc مباشرة فوق عناصر التعليمات البرمجية التي تريد توثيقها. استخدام /\*_ ... _/ بناء الجملة للإشارة إلى كتلة تعليقات JSDoc . -2. وظائف التوثيق: استخدام علامات JSDoc لوصف معلمات الدالة، قيم الإرجاع، ومعلومات إضافية. العلامات مثل @param و @returs و @description شائعة الاستخدام لهذا الغرض. العلامات المخصصة المهمة الأخرى هي @category و @subcategory، هذه العلامات تساعد في هيكلة الوثائق التي تم إنشاؤها في فصول. وستكون جميع الوحدات تحت `فئة فرعية` تحت فصل واحد، وسيتطابق اسم الفصل مع الاسم المعين لـ `الفئة الفرعية`. - الفكرة الرئيسية حول @category وsubcategory هي السماح للفصول المتداخلة، على سبيل المثال، يمكن أن يحتوي الفصل الأصلي A على فصول فرعية أخرى (الفصل Aa، الفصل Ab، الفصل Ac) مع وجود كل فصل من هذه الفصول الفرعية بوحداته الفردية. - لاحظ أن هذا هو مستويين فقط من التعقيد، حيث أن الفصل ألف هو الفئة @والفئة الفرعية @@ ستكون هي الفصول الأخرى. نعتزم في البداية تنفيذ مستويين من الفصول المتداخلة، ولكن هذا في وقت كتابة هذا الربع لا يسمح إلا لمستوى واحد من التعبيد (١). +2. وظائف التوثيق: استخدام علامات JSDoc لوصف معلمات الدالة، قيم الإرجاع، ومعلومات إضافية. العلامات مثل @param و @returs و @description شائعة الاستخدام لهذا الغرض.
+ Other important custom tags are @category and @subcategory, these tags help to structure the generated documentation into chapters.
+ - @category: This tag is used to group modules under a common chapter. All modules under a `category` will be under one chapter, the chapter name will correspond to the name assigned to the `category`. + - @subcategory: This tag is used to group modules under a common chapter. +وستكون جميع الوحدات تحت `فئة فرعية` تحت فصل واحد، وسيتطابق اسم الفصل مع الاسم المعين لـ `الفئة الفرعية`. + + + + + + 3. فئات التوثيق: بالنسبة للصفوف الدراسية، استخدم تعليقات JSDoc لتوفير الأوصاف، وخصائص الصف المستندي، وطرائق فصل المستند. العلامات مثل @clas, @property و @method تستخدم عادة في هذا السياق. @@ -23,8 +31,9 @@ title: Improving documentation للمزيد من المعلومات حول استخدام JSDoc لتوليد الوثائق، انظر [وثائق JSDoc](https://jsdoc.app/) أو [Getting بدأ باستخدام JSDoc](https://jsdoc.app/about-getting-started.html). -### استخدام JSDoc للتوثيق الوراثي +### استخدام JSDoc للتوثيق الوراثي +
يمكن أيضًا استخدام JSDoc خارج نطاق إنشاء وثائق التعليمات البرمجية. نظام بناء الجملة والعلامة المرن لديه يجعله أداة قيمة لكتابة الجوانب الأخرى من وثائق مشروعك، مثل البرامج التعليمية والإرشادية والمواد المرجعية. لاستخدام JSDoc لكتابة الوثائق، ضع في الاعتبار النهج التالية: @@ -37,181 +46,17 @@ title: Improving documentation 4. التكامل مع Markdown: JSDoc يدعم Markdown ضمن التعليقات، مما يسمح لك بإدماج النصوص المنسقة والعناوين والقوائم وغيرها من ميزات Markdown في وثائقك. هذا يمكّنك من إنشاء محتوى أكثر جاذبية بصرياً وتنظيماً في تعليقات JSDoc الخاصة بك. +### ### تحسين وثائق JSQuarto باستخدام JSDoc - +
لم تكتمل بعد وثائق JSQuarto. وهناك عدة مجالات يمكن تحسينها، منها: - إيضاحات أكثر تفصيلا لهيكل مشروع JSQuarto ومشروع الترميز - معلومات إضافية عن كيفية المساهمة في هذا المشروع -- تنفيذ JSQuarto كأداة من أدوات المبادرة القطرية - معلومات إضافية عن كيفية الحفاظ على مشروع JSQuarto - معلومات إضافية عن كيفية المساهمة في هذا المشروع - خريطة الطريق للمشروع والخطط المستقبلية لتحسين وثائق JSQuarto ، يمكنك استخدام JSDoc لإضافة وثائق إضافية مباشرة داخل المركز البرمجي. سيسمح لك هذا بتقديم تفسيرات أكثر تفصيلاً للكود وبنية المشروع، بالإضافة إلى معلومات إضافية حول كيفية المساهمة في المشروع، وكيفية استخدام JSQuarto API، وكيفية صيانة المشروع ونشره. في وقت كتابة هذا، تم بناء الوثائق مع حزم أخرى لتحسين واجهة المستخدم، أحدها [Better-docs](https://github.com/SoftwareBrothers/better-docs). -### دليل الدروس - -يقدم هذا القسم لمحة عامة عن ملفات `config.json` المستخدمة في وثائق JSQuarto، مع التركيز تحديداً على مجلد `tutorials`. ملف `config.json' يعمل كملفات تكوين تساعد على هيكلة وتنظيم الوثائق، في حين يحتوي مجلد `الدروس` على ملفات Markdown لمختلف الدروس. - -#### مجلد `الدروس التعليمية` - -مجلد "الدروس" داخل دليل التوثيق مكرس لاستضافة دروس حول مختلف المواضيع ذات الصلة بمنصة JSQuarto. يحتوي هذا المجلد على مجموعة من ملفات Markdown، يمثل كل منها درسا فرديا. - -Markdown هي لغة علامة خفيفة الوزن تسمح بسهولة تنسيق وبنية النص، مما يجعلها مثالية لإنشاء دروس. توفر ملفات Markdown طريقة بسيطة ولكنها قوية لتوثيق التعليمات خطوة بخطوة، والأمثلة البرمجية، والتفسيرات وغيرها من المعلومات ذات الصلة. - -يمكن تنظيم مجلد "الدروس" في مجلدات فرعية لزيادة تصنيف ودروس ذات صلة بالمجموعة. وهذا يساعد المستخدمين على تحديد مواقع الدروس التي يحتاجونها بسهولة والوصول إليها بناء على اهتماماتهم أو متطلباتهم المحددة. - -من خلال هيكلة الدروس داخل مجلد "الدروس" باستخدام Markdown، يمكن للمساهمين المساهمة بدروس جديدة، تحديث الوثائق الموجودة، وضمان أن تظل الوثائق شاملة وسهلة الاستعمال. - -ملفات son` ومجلد "الدروس التعليمية" يمكنان من بنية وثائق منظمة تنظيماً جيداً ويمكن الوصول إليها، مما يسمح للمستخدمين بالتنقل واستكشاف وثائق منصة JSQuarto بسهولة. - -#### نظرة عامة على ملفات `config.json` - -يؤدي ملف `config.json' في وثائق JSQuarto دورا حاسما في تنظيم وتصنيف المحتوى. يحدد هذا الملف هيكل الوثائق ويوفر بيانات فوقية لكل قسم أو برنامج تعليمي أو موضوع. فهي تسمح للقائمين على الصيانة والمساهمين بالتنقل في الوثائق وإدارتها بسهولة عن طريق تحديد العناوين وإنشاء هياكل متداخلة وربط المواضيع ذات الصلة. - -باستخدام ملف `config.json' ، يمكن إنشاء الوثائق وتحديثها ديناميكيا استنادا إلى الهيكل المحدد. وهذا يجعل من الأسهل المحافظة على الاتساق، وتتبع التغييرات، وإضافة محتوى جديد. - - -#### إعدادات `.json` -لنشرح كيف تعمل هذه البنية من خلال النظر إلى ملف `config.json' في مجلد `tutorials /'. يحدد هذا الملف هيكل قسم الدروس في الوثائق، بما في ذلك العناوين، وصلات الوصف لكل درس تعليمي. - -```json -{ - "سجل التغييرات": { - "العنوان: "التغيير" - }, - "environment_setup": { - "العنوان": "إعداد البيئة" - }, - "المساهمة": { - "العنوان": "المساهمة" - } -} -``` - -في هذا المثال ، يحدد ملف 'json' عناوين وعلاقات الأقسام الرئيسية داخل وثائقك. الأقسام ممثلة ككائنات، مع كل كائن له مفتاح فريد و 'title"` في زوج القيمة الرئيسية. -1. "سجل التغييرات" يمثل قسم "التغييرات". يحدد زوج القيمة الرئيسية "title" عنوان هذا القسم كـ "التغيير". - -2. "environment_setup" يمثل قسم "إعداد البيئة". يحدد زوج القيمة الرئيسية "title" عنوان هذا القسم بأنه "إعداد البيئة". - -3. يمثل "المساهمة" قسم "المساهمة". يحدد زوج القيمة الرئيسية "title" عنوان هذا القسم كـ "التغيير". - -بهذه البنية، سيحتوي مجلد الوثائق الخاص بك على ملفات Markdown منفصلة لكل قسم، يتم تسميتها وفقًا للمفاتيح الموجودة في ملف `.json`. على سبيل المثال: - -“يامل -- `الوثائق/` - - `docs /` - - `changelog.md` - - `environment_setup.md` - - `contributing.md` - - `tutorials.json` -``` - -كل ملف Markdown سيتطابق مع قسم في وثائقك ويجب أن يحتوي على المحتوى ذي الصلة لذلك القسم. - -هذا الهيكل المبسط يسمح لك بتنظيم الوثائق الخاصة بك في أقسام متميزة، يجعل من الأسهل على القراء تحديد مواقع المواضيع المحددة التي يحتاجون إليها والوصول إليها. توفر طريقة واضحة وموجزة لتمثيل الأقسام الرئيسية من وثائقك دون الحاجة إلى دروس متداخلة أو تسلسل هرمي معقد. - -تذكر أن تقوم بتحديث ملف '.json' كلما قمت بإضافة أو تعديل الأقسام للتأكد من أن هيكل التوثيق يعكس بدقة محتوى وثائقك. - -باتباع هذا الهيكل، يمكنك الحفاظ على مستودع وثائق جيد التنظيم وسهل التصفح. - -#### إعدادات `.json` المتداخلة للدورات التعليمية -لهيكلة الدروس وإنشاء دروس متداخلة داخل وثائقك، يمكنك استخدام ملف '.json' لتحديد التسلسل الهرمي والعلاقات بين الدروس. إليك مثال على كيفية هيكلة الدروس باستخدام ملف `.json`: - -“يامل -{ - "المشرفين": { - "العنوان": "دليل تقني للقائمين"، - "الأطفال": { - "reviewing_pr": { - "title": "استعراض طلبات السحب" - }, - "ci_workflow": { - "title": "CI Workflow " - }, - "الأسرار_and_security": { - العنوان : "الوصول السري/الإدارة السرية" - }, - "نشر الدليل": { - "عنوان": "دليل النشر" - } - } - }, - "المساهمة": { - "title": "المساهمة في المشروع"، - "الأطفال": { - "adding_a_course": { - "title": "إضافة دورة" - }, - "api_project_structure": { - "title": "بنية مشروع API - }, - "Improving_documentation": { - العنوان : "تحسين التوثيق" - }, - "project_structure": { - "عنوان": "بنية المشروع" - }, - "raising_issues": { - العنوان: "إثارة المشاكل" - }, - "raising_pr": { - "عنوان": "رفع طلبات الجذب" - } - } - }, - "عرض": { - "title": "استعراض المشروع" - } -} - ``` - -وفي هذا المثال، يمثل ملف `json` هيكلا للتوثيق يتألف من قسمين رئيسيين: "الدليل التقني للمتعينين" و"الدليل التقني لمطوري API". لكل قسم مجموعته الخاصة من الدروس التي تمثل ككائنات متداخلة. - -1. تعريف الأقسام أو الفئات الرئيسية على أنها الكائنات ذات المستوى الأعلى داخل ملف `json'، مثل "المشرفين" و "المساهمة". - -2. ضمن كل قسم رئيسي، قدم مفتاح "عنوان" لتحديد عنوان أو عنوان ذلك القسم. () على سبيل المثال، "الدليل التقني للقائمين" و"الدليل التقني لمطوري API". - -3. إضافة مفتاح 'الأطفال' داخل كل قسم رئيسي لتحديد الدروس المتداخلة. يتم تمثيل كل برنامج تعليمي ككائن ثانوي داخل كائن `الأطفال`. وقد لا تحتوي جميع الدروس على دروس للأطفال، ومن الأمثلة على ذلك دروس "مراجعة". بما أنه ليس لديه أطفال فإن البرنامج سيبحث فقط عن ملف "review.qmd" وليس مجلد "عرض" - -4. لكل برنامج تعليمي، قم بتوفير مفتاح فريد كمفتاح الكائن، مثل "reviewing_pr" و "ci_workflow". - -5. ضمن كل كائن تعليمي، قم بإدراج مفتاح "title" لتحديد العنوان أو العنوان لذلك البرنامج التعليمي المحدد. - -على هذا المثال هنا ما سيبدو عليه هيكل المجلد بافتراض أن المجلد الجذري هو `دروس/`: - -“يامل - - دروس/دروس - - المشرفون/ - - المشرفون - - الاستعراض_pr.qmd - - ci_workflow.qmd - - الأسرار_and_security.qmd - - نشر_guide.qmd - - - المساهمة/ - - api.md - - api_structure.md - - api_authentication_flow.qmd - - jwt_token_management.qmd - - rbac_handler_flow.qmd - - - review.qmd - - - config.json -``` - -وفي هذا الهيكل: - -- ملف التكوين 'json' موجود في المجلد 'دروس التعليمية' -- يحتوي مجلد "الدروس" على مجلدات فرعية تمثل أقسام أو فئات مختلفة من الدروس. -- كل قسم أو مجلد فئة، مثل 'المشرفين` و 'المساهمة`، يحتوي على ملفات '.qmd' لدروس فردية. - - -الهيكل المتداخل يسمح لك بتنظيم الدروس هرمياً ، مما يجعل من الأسهل التنقل والبحث عن دروس محددة استناداً إلى موضوعها أو فئتها. - -من المهم ملاحظة أن بنية البرنامج التعليمي لا تسمح إلا بمستوى واحد من التعش. هذا يعني أنه يمكنك الحصول على الأقسام الرئيسية ودروسها، ولكن لا يمكنك إنشاء المزيد من المجلدات المتداخلة داخل الدروس. - -md` ملفات نظرة عامة، يمكنك بسهولة تحديد التسلسل الهرمي والعلاقات بين الدروس، السماح لك بإنشاء دروس متداخلة وتنظيم وثائقك بطريقة منطقية ومنظمة. From 0a9aca50359f5d399ce44f082bf66498ebc5e41d Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Thu, 4 Jul 2024 00:04:37 +0100 Subject: [PATCH 5/6] New translations environment_setup.qmd (Arabic, Saudi Arabia) --- .../ar/chapters/tutorials/environment_setup.ar.qmd | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/_translations/ar/chapters/tutorials/environment_setup.ar.qmd b/docs/_translations/ar/chapters/tutorials/environment_setup.ar.qmd index 18d02a39..d4cf3528 100644 --- a/docs/_translations/ar/chapters/tutorials/environment_setup.ar.qmd +++ b/docs/_translations/ar/chapters/tutorials/environment_setup.ar.qmd @@ -1,17 +1,16 @@ --- title: Environment_setup --- -- -title: 'إعداد البيئة' -- -#### Prerequisites {#environment-setup} +### Prerequisites {#environment-setup} +
قبل اختبار الأداة محلياً، تأكد من وجود الشروط المسبقة التالية مثبتة على النظام الخاص بك: - Node.js و npm (مدير الحزمة العقدية) - Git (اختياري، إذا استنساخ المستودع) - Babel Quarto (optional, if previewing the generated documentation) -#### التثبيت +### Installation +
لاختبار الأداة محلياً، قم باتباع الخطوات التالية: 1. Install the cli package from NPM: @@ -26,6 +25,7 @@ title: 'إعداد البيئة' ### تشغيل الأداة +
1. لإنشاء الوثائق قم بتشغيل الأمر التالي “`باش From cd363378e79d9694a4f9d344adf3983f49aa6323 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Thu, 4 Jul 2024 00:04:39 +0100 Subject: [PATCH 6/6] New translations usage.qmd (Arabic, Saudi Arabia) --- .../ar/chapters/tutorials/how_to/usage.ar.qmd | 30 +++++++++++++------ 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/docs/_translations/ar/chapters/tutorials/how_to/usage.ar.qmd b/docs/_translations/ar/chapters/tutorials/how_to/usage.ar.qmd index 55c620e8..e0fd233f 100644 --- a/docs/_translations/ar/chapters/tutorials/how_to/usage.ar.qmd +++ b/docs/_translations/ar/chapters/tutorials/how_to/usage.ar.qmd @@ -4,10 +4,12 @@ title: Usage This section provides an overview of the JSquarto tool and its usage, including the custom CLI arguments and configuration settings that can be leveraged to customize the documentation generation process. ### CLI arguments {#sec-usage} +
يتم استخدام حجج CLI لتخصيص سلوك أداة JSquarto هذه الحجج المفصلة تمكنك من تصميم عملية توليد الوثائق بما يناسب متطلباتك المحددة. “`باش “`باش “`باش “`باش “`باش “`باش “`باش “`باش “`باش “`باش “`باش “`باش “`باش “`باش “`باش وبالاستفادة من هذه الحجج، يمكنك تعزيز كفاءة وفعالية عملية توليد الوثائق، مما يؤدي إلى تبسيط سير العمل الخاص بك وتحسين إنتاج الوثائق الخاصة بك. “`باش “`باش “`باش “`باش “`باش “`باش “`باش “`باش “`باش “`باش “`باش “`باش “`باش “`باش وبالاستفادة من هذه الحجج، يمكنك تعزيز كفاءة وفعالية عملية توليد الوثائق، مما يؤدي إلى تبسيط سير العمل الخاص بك وتحسين إنتاج الوثائق الخاصة بك. بعض حجج CLI المخصصة المدعومة من JSquarto تشمل: -1. `source`: Source files are pivotal components containing the comments that JSquarto utilizes to generate comprehensive documentation. يحدد الدليل الذي يحتوي على الملفات المصدر التي سيتم توثيقها. يمكن كتابة هذه الملفات بلغات مختلفة مدعومة من JSquarto، مثل JavaScript و TypeScript و JSX. By default, JSquarto will check for the `docs/source` directory within your project structure to locate these the source file. However, you possess the flexibility to designate an alternative directory through the `source` option. + +1. `source`: Specifies the directory containing the source files to be documented. يمكن كتابة هذه الملفات بلغات مختلفة مدعومة من JSquarto، مثل JavaScript و TypeScript و JSX. By default, JSquarto will check for the `docs/source` directory within your project structure to locate these the source file. However, you possess the flexibility to specify an alternative directory through the `source` option. 2. `tutorial`: Specifies the directory containing the tutorial files to be included in the documentation. هذه الحجة تسمح لك بإدماج المحتوى التعليمي في وثائقك، وتوفير سياق إضافي وإرشادات للمستخدمين. @@ -18,6 +20,7 @@ This section provides an overview of the JSquarto tool and its usage, including 5. `include_localized_versions`: يحدد ما إذا كان ينبغي إدراج إصدارات موضعية من الوثائق التي تم إنشاؤها. على سبيل المثال، إذا تم تحديدها، سيقوم JSquarto بإنشاء ملفات منفصلة لكل لغة محددة. ### تكوين +
ملف `config.json' في الدليل الجذر للمشروع يستخدم لتخزين إعدادات التكوين لأداة JSquarto . يحتوي هذا الملف على الإعدادات الافتراضية لعملية توليد الوثائق، مثل دليل الملفات المصدر، ودليل الملفات التعليمية، ودليل الإخراج، واللغات المعتمدة. This config file can come in handy when you want to persist your settings for a particular project. يمكنك تعديل هذه الإعدادات لتخصيص عملية توليد الوثائق وفقا لتفضيلاتك. Below is an example of the `config.json` file: @@ -33,6 +36,7 @@ Below is an example of the `config.json` file: ``` It contains the following fields: + 1. `المصدر`: يحدد الدليل الذي يحتوي على الملفات المصدرية التي يتعين توثيقها. By default, this field is set to `docs/source` within the project structure. This is the same as the `source` CLI argument. 2. `دليل الدروس`: يحدد الدليل الذي يحتوي على ملفات الدرس التعليمي التي ستدرج في الوثائق. By default, this field is set to `docs/tutorials` within the project structure. This is the same as the `tutorial` CLI argument. @@ -41,6 +45,7 @@ It contains the following fields: ### Basic Usage {#sec-basic-usage} +
لاستخدام حجج CLI المخصصة هذه، ببساطة قم بإلحاقها بأمر JSquarto عند تنفيذ الأداة. على سبيل المثال: لتحديد دليل ملفات المصدر: @@ -73,19 +78,23 @@ jsq doc:generate include_localized_versions=true languages=en,fr,es ملاحظة: إذا كنت تنوي 'include_localized_versions`، فيجب عليك أيضا تحديد حجة 'اللغات` للإشارة إلى اللغات المؤيدة للوثائق. ### Usage with Configuration File {#sec-config-usage} +
Alternatively, you can leverage the `config.json` file to store your custom settings and avoid specifying them each time you run the JSquarto tool. By modifying the fields in the `config.json` file, you can customize the documentation generation process according to your requirements. To use a configuration file follow the steps below: + 1. Initialize the configuration file using the command below: - “`باش - jsq config:init - ``` + + “`باش + jsq config:init + ``` This will create a `config.json` file in the `.jsquarto` directory within your project structure. You might have an already existing config file, for this case you can tell jsq to use this file instead by running; - “`باش - jsq config:set config=/path/to/your/directory - ``` + + “`باش + jsq config:set config=/path/to/your/directory + ``` -2. Set the desired configuration settings in the `config.json` file according to your preferences. +2. Set the desired configuration settings in the `config.json` file according to your preferences.
To set the source files directory run “`باش jsq config:set source=/path/to/your/source/files @@ -114,7 +123,8 @@ This will update the `config.json` file with the specified settings, which will You can also manually edit the `config.json` file to modify the configuration settings according to your requirements. -#### ::: {.notes} +#### +::: {.notes} **Note:** - After initializing a config file the default configuration will be added to the file. You can then modify the settings in the file to suit your needs. @@ -123,6 +133,7 @@ You can also manually edit the `config.json` file to modify the configuration se - Even when you have multiple projects, jsquarto will store the config file location for each project separately. This means that you can have different config files for different projects. - If you already initialized a config file for project, and you want to use a different config file for the same project, you can run the command below: + “`باش jsq config:set config=/path/to/your/directory force ``` @@ -130,6 +141,7 @@ You can also manually edit the `config.json` file to modify the configuration se ::: ### الاستفادة من TypeScript في ملفات المصدر +
عند استخدام TypeScript ضمن مشروعك، من المستصوب تحويل ملفات مصدر TypeScript إلى JavaScript قبل بدء عملية JSquarto . تنبع هذه التوصية من حقيقة أن JSquarto تفتقر إلى الدعم الجوهري لجملة TypeScript. بمجرد أن تقوم بنقل ملفات TypeScript الخاصة بك إلى JavaScript، يمكنك تنفيذ JSquarto بسلاسة على ملفات JavaScript الناتجة لإنشاء وثائق شاملة. دمج نقل TypeScript