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

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

بعض حجج CLI المخصصة المدعومة من JSquarto تشمل:

  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. هذه الحجة تسمح لك بإدماج المحتوى التعليمي في وثائقك، وتوفير سياق إضافي وإرشادات للمستخدمين.

  3. output: Specifies the output directory where the generated documentation will be stored. By default, JSquarto will save the documentation in the docs directory within your project structure. However, you can customize the output location by specifying an alternative directory through the output option.

  4. ‘اللغات: يحدد اللغات التي ينبغي دعمها في الوثائق. هذه الحجة تمكنك من توليد الوثائق بلغات متعددة، وتغذي قاعدة متنوعة من المستخدمين. فعلى سبيل المثال، تحددlanguages=en,fr,es’ اللغات الانكليزية والفرنسية والإسبانية بوصفها اللغات المدعومة.

  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:

{
    "includeLocalizedVersions": false,
    "outputDirectory": "docs/output",
    "sourceDirectory": "docs/source",
    "tutorialDirectory": "docs/tutorials",
    "languages": ["en", "ar"],
    "translationsDirectory": "dosc/translations"
}

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.

  3. ’دليل النواتج: يحدد دليل المخرجات حيث سيتم تخزين الوثائق التي تم إنشاؤها. By default, this field is set todocs/outputwithin the project structure. This is the same as theoutput` CLI argument.

Basic Usage

لاستخدام حجج CLI المخصصة هذه، ببساطة قم بإلحاقها بأمر JSquarto عند تنفيذ الأداة. على سبيل المثال:

لتحديد دليل ملفات المصدر: “`باش jsq doc:generate source=/path/to/your/source/files


لتحديد دليل ملفات البرنامج التدريبي:
“`باش
jsq doc:generate tutorial=/path/to/your/tutorial/files

لتحديد دليل الإخراج: “`باش jsq doc:generate output=/path/to/your/output/directory


لتحديد اللغات المعتمدة:
“`باش
jsq doc:generate languages=en,fr,es

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

لإدراج النسخ المترجمة للوثائق التي تم إنشاؤها: “`باش jsq doc:generate include_localized_versions=true languages=en,fr,es

سيؤدي هذا إلى توليد الوثائق باللغات المحددة وأيضاً إضافة اللغات إلى ملف التكوين (_quarto.yml).

ملاحظة: إذا كنت تنوي 'include_localized_versions`، فيجب عليك أيضا تحديد حجة 'اللغات` للإشارة إلى اللغات المؤيدة للوثائق.

### Usage with Configuration File {#sec-config-usage}
<hr>
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  
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 ```

  1. 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

    
To set the tutorial files directory run
“`باش
jsq config:set tutorial=/path/to/your/tutorial/files

    To set the output directory run “باش jsq config:set output=/path/to/your/output/directory ``` To set the supported languages run “باش jsq config:set languages=en,fr,es

    
To include localized versions of the generated documentation run
“`باش
jsq config:set include_localized_versions=true

This will update the config.json file with the specified settings, which will be used by the JSquarto tool during the documentation generation process.

You can also manually edit the config.json file to modify the configuration settings according to your requirements.

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.

  • Your config.json file location will be stored by jsquarto in cache, so you don’t have to specify the file location each time you run jsquarto. It is stored together with your project directory (the directory where jsq command is run).

  • 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 ``` This will update the config file location for the project.

الاستفادة من TypeScript في ملفات المصدر

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

دمج نقل TypeScript قبل تنفيذ JSquarto، تأكد من تحويل ملفات مصدر TypeScript إلى JavaScript باستخدام المحول المفضل، مثل TypeScript Compiler (tsc). وتكفل هذه الخطوة التواؤم مع عملية توليد الوثائق في JSquarto، مما ييسر سلاسة وكفاءة