From ee6e5fc3ac2765c812450e9e925efb87e8d5ce6c Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 02:16:33 +0100 Subject: [PATCH 01/61] Update Crowdin configuration file --- crowdin.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crowdin.yml b/crowdin.yml index 2630349c..c82d255d 100644 --- a/crowdin.yml +++ b/crowdin.yml @@ -1,7 +1,7 @@ files: - source: /docs/**/*.qmd - translation: /translation/%two_letters_code%/%original_path%/%original_file_name%.%two_letters_code%.%file_extension% + translation: /translations/%two_letters_code%/%original_path%/%original_file_name%.%two_letters_code%.%file_extension% - source: /docs/**/*.md - translation: /translation/%two_letters_code%/%original_path%/%original_file_name%.%two_letters_code%.%file_extension% + translation: /translations/%two_letters_code%/%original_path%/%original_file_name%.%two_letters_code%.%file_extension% bundles: - 4 From 09b1cac1ce0df1db8aa1ddfc4f407d7c56e9a1d5 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 02:16:41 +0100 Subject: [PATCH 02/61] New translations index.qmd (Arabic, Saudi Arabia) --- translations/ar/docs/chapters/functional doc/index.qmd.ar.qmd | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 translations/ar/docs/chapters/functional doc/index.qmd.ar.qmd diff --git a/translations/ar/docs/chapters/functional doc/index.qmd.ar.qmd b/translations/ar/docs/chapters/functional doc/index.qmd.ar.qmd new file mode 100644 index 00000000..9cfe7567 --- /dev/null +++ b/translations/ar/docs/chapters/functional doc/index.qmd.ar.qmd @@ -0,0 +1,3 @@ +--- +title: Functional doc +--- From 45f19c028aa5dc8a1b13e0fdf6aed7690bf08125 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 02:16:41 +0100 Subject: [PATCH 03/61] New translations commentsutil.qmd (Arabic, Saudi Arabia) --- .../utilities/commentsutil.qmd.ar.qmd | 95 +++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 translations/ar/docs/chapters/functional doc/utilities/commentsutil.qmd.ar.qmd diff --git a/translations/ar/docs/chapters/functional doc/utilities/commentsutil.qmd.ar.qmd b/translations/ar/docs/chapters/functional doc/utilities/commentsutil.qmd.ar.qmd new file mode 100644 index 00000000..d044077f --- /dev/null +++ b/translations/ar/docs/chapters/functional doc/utilities/commentsutil.qmd.ar.qmd @@ -0,0 +1,95 @@ +# Commentsutil + +this file provides utility classes for parsing and extracting information + from comments within code files. it includes methods to identify and + extract metadata from both module and non-module comments, + facilitating better documentation and understanding of code constructs + such as functions, variables, classes, and modules. + + + +## moduleName +`[variable]` + +**Description:** +This method extracts module block information from comments, including module name, description, category, subcategory, link, and references. + +**Params:** + +| Name | Description | +| --- | --- | +| comments | The comments to extract module block information from. | + + + +## description +`[variable]` + +**Description:** +This method extracts other block information from comments, including description, params, link, examples, returns, thrown errors, and references. + +**Params:** + +| Name | Description | +| --- | --- | +| comments | The comments to extract other block information from. | + + + +## fileContent +`[variable]` + +**Description:** +This method retrieves comments from a source file using Acorn parser. + +**Params:** + +| Name | Description | +| --- | --- | +| sourceFile | The source file to retrieve comments from. | + + + +## unknown +`[other]` + +**Description:** +This class represents a comment extracted from a source file. + +**Params:** + +| Name | Description | +| --- | --- | +| text | The text content of the comment. | +| endLocation | The end location of the comment. | + + + +## unknown +`[function]` + +**Description:** +This method sets the construct information of the comment, including the type and name of the construct. + +**Params:** + +| Name | Description | +| --- | --- | +| info | The construct information to set. | + + + +## unknown +`[other]` + +**Description:** +This method retrieves module block information from the comment using the CommentsUtil class. + + + +## unknown +`[other]` + +**Description:** +This method retrieves other block information from the comment using the CommentsUtil class. + From 63bc5d59c32458480f55fdf72aa507611682fd62 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 02:16:42 +0100 Subject: [PATCH 04/61] New translations components.qmd (Arabic, Saudi Arabia) --- .../utilities/components.qmd.ar.qmd | 211 ++++++++++++++++++ 1 file changed, 211 insertions(+) create mode 100644 translations/ar/docs/chapters/functional doc/utilities/components.qmd.ar.qmd diff --git a/translations/ar/docs/chapters/functional doc/utilities/components.qmd.ar.qmd b/translations/ar/docs/chapters/functional doc/utilities/components.qmd.ar.qmd new file mode 100644 index 00000000..31921ad8 --- /dev/null +++ b/translations/ar/docs/chapters/functional doc/utilities/components.qmd.ar.qmd @@ -0,0 +1,211 @@ +# Components + +this module is used to generate the quarto yml file + + + + +## recursivelyConvertAllStringValuesInObjectToLowerCase +`[function]` + +**Description:** +Recursively convert all string values in an object to lowercase + + +**Examples:** + +```javascript +const obj = { + name: 'Hello World', + description: 'This is a description', + blockInfo: { + name: 'Hello World', + description: 'This is a description', + }, + }; + recursivelyConvertAllStringValuesInObjectToLowerCase(obj); + // => { + // name: 'hello world', + // description: 'this is a description', + // blockInfo: { + // name: 'hello world', + // description: 'this is a description', + // }, + // } +``` + + + +## unknown +`[other]` + +**Description:** +Add a document to the module + + +**Examples:** + +```javascript +const module = new Module({ name: 'StringUtil' }); + const moduleDoc = new ModuleDoc({ + originalFilePath: 'string.ts', + data: { + + blockInfo: { + name: 'StringUtil', + description: 'This class contains methods for manipulating strings', + }, + constructInfo: { + type: 'class', + name: 'StringUtil', + }, + }, + }); + module.addDoc(moduleDoc); +``` + + + +## unknown +`[other]` + +**Description:** +Get the documents in the module + + +**Examples:** + +```javascript +const module = new Module({ name: 'StringUtil' }); + const moduleDoc = new ModuleDoc({ + originalFilePath: 'string.ts', + data: { + blockInfo: { + name: 'StringUtil', + description: 'This class contains methods for manipulating strings', + }, + constructInfo: { + type: 'class', + name: 'StringUtil', + }, + }, + }); + module.addDoc(moduleDoc); + module.getDocs(); + // => [ModuleDoc] +``` + + + +## unknown +`[other]` + + + +## unknown +`[other]` + +**Description:** +sets the source file path + + + + +## unknown +`[other]` + +**Description:** +Add a module to the subcategory + + + + + +## unknown +`[other]` + +**Description:** +Get the modules in the subcategory + + + + + +## unknown +`[other]` + +**Description:** +Get the name of the subcategory + + + + +## Category +`[class]` + + + +## unknown +`[other]` + +**Description:** +This class represents a category. + +**Params:** + +| Name | Description | +| --- | --- | +| name | The name of the category. | + + + +## unknown +`[other]` + +**Description:** +Adds a subcategory to the category. + +**Params:** + +| Name | Description | +| --- | --- | +| subCategory | The subcategory to add. | + + + +## unknown +`[other]` + +**Description:** +Retrieves the subcategories in the category. + + + +## unknown +`[other]` + +**Description:** +Retrieves the name of the category. + + + +## unknown +`[other]` + +**Description:** +Adds a module to the category. + +**Params:** + +| Name | Description | +| --- | --- | +| module | The module to add. | + + + +## unknown +`[other]` + +**Description:** +Retrieves the modules in the category. + From dc17f56e5b0a5349e19e9c7661c662c8cd084f2c Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 02:16:43 +0100 Subject: [PATCH 05/61] New translations constructidentifier.qmd (Arabic, Saudi Arabia) --- .../utilities/constructidentifier.qmd.ar.qmd | 102 ++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 translations/ar/docs/chapters/functional doc/utilities/constructidentifier.qmd.ar.qmd diff --git a/translations/ar/docs/chapters/functional doc/utilities/constructidentifier.qmd.ar.qmd b/translations/ar/docs/chapters/functional doc/utilities/constructidentifier.qmd.ar.qmd new file mode 100644 index 00000000..8dbd7459 --- /dev/null +++ b/translations/ar/docs/chapters/functional doc/utilities/constructidentifier.qmd.ar.qmd @@ -0,0 +1,102 @@ +# Constructidentifier + +the class called constructidentifier, contains methods to identify different types of code constructs + (such as functions, variables, classes, and modules) within a line of code. + these methods help in extracting and determining the names associated with each construct type. + + + +## ConstructIdentifier +`[class]` + + + +## unknown +`[function]` + +**Description:** +Retrieves the name of the module construct from a given line of code. + + + +**Params:** + +| Name | Description | +| --- | --- | +| line | The line of code to parse. | + + + +## variableX +`[function]` + +**Description:** +Retrieves the name of the function construct from a given line of code. + + + +**Params:** + +| Name | Description | +| --- | --- | +| line | The line of code to parse. | + + + +## variableRegex +`[variable]` + +**Params:** + +| Name | Description | +| --- | --- | +| line | The line of code to parse. | + + + +## classRegex +`[variable]` + +**Description:** +Retrieves the name of the class construct from a given line of code. + + + +**Params:** + +| Name | Description | +| --- | --- | +| line | The line of code to parse. | + + + +## declarationconst +`[function]` + +**Description:** +Identifies the type of construct (function, variable, class, module, other) from the given code text. + + + +**Params:** + +| Name | Description | +| --- | --- | +| text | The code text to analyze. | + + + +## unknown +`[function]` + +**Description:** +Retrieves the name of the construct from the given code text. + + + +**Params:** + +| Name | Description | +| --- | --- | +| text | The code text to analyze. | + From 0e8e22793a938924e4b5b65790f1af1b38641b86 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 02:16:44 +0100 Subject: [PATCH 06/61] New translations file.qmd (Arabic, Saudi Arabia) --- .../functional doc/utilities/file.qmd.ar.qmd | 34 +++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 translations/ar/docs/chapters/functional doc/utilities/file.qmd.ar.qmd diff --git a/translations/ar/docs/chapters/functional doc/utilities/file.qmd.ar.qmd b/translations/ar/docs/chapters/functional doc/utilities/file.qmd.ar.qmd new file mode 100644 index 00000000..8038ddcb --- /dev/null +++ b/translations/ar/docs/chapters/functional doc/utilities/file.qmd.ar.qmd @@ -0,0 +1,34 @@ +# File + +this module is used to read and write files + + + this file reads and analyzes source code files. + it identifies the type and name of the code construct linked + to a given comment by examining the lines following the comment, + utilizing the constructidentifier class. + + + +## unknown +`[other]` + +**Description:** +This method returns the type and name of the code construct linked to a comment + + + +**Examples:** + +```javascript +const file = new SourceFile('file.ts'); + + const comment = new Comment({ + startLocation: { line: 1, column: 1 }, + endLocation: { line: 1, column: 1 }, + content: 'This is a comment' + }); + file.getLinkedCodeConstructInfo(comment); + // => { type: 'class', name: 'StringUtil' } +``` + From f849a519ca096dcaefca97910e05a556070d3cc5 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 02:16:44 +0100 Subject: [PATCH 07/61] New translations index.qmd (Arabic, Saudi Arabia) --- .../ar/docs/chapters/functional doc/utilities/index.qmd.ar.qmd | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 translations/ar/docs/chapters/functional doc/utilities/index.qmd.ar.qmd diff --git a/translations/ar/docs/chapters/functional doc/utilities/index.qmd.ar.qmd b/translations/ar/docs/chapters/functional doc/utilities/index.qmd.ar.qmd new file mode 100644 index 00000000..029c7d18 --- /dev/null +++ b/translations/ar/docs/chapters/functional doc/utilities/index.qmd.ar.qmd @@ -0,0 +1,3 @@ +--- +title: utilities +--- From f92e01ddc0bbf6101deeac4a92ad9bcd44aaeda3 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 02:16:45 +0100 Subject: [PATCH 08/61] New translations logger.qmd (Arabic, Saudi Arabia) --- .../docs/chapters/functional doc/utilities/logger.qmd.ar.qmd | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 translations/ar/docs/chapters/functional doc/utilities/logger.qmd.ar.qmd diff --git a/translations/ar/docs/chapters/functional doc/utilities/logger.qmd.ar.qmd b/translations/ar/docs/chapters/functional doc/utilities/logger.qmd.ar.qmd new file mode 100644 index 00000000..7eff27c6 --- /dev/null +++ b/translations/ar/docs/chapters/functional doc/utilities/logger.qmd.ar.qmd @@ -0,0 +1,5 @@ +# Logger + +this module is used to log messages to the console + + From b3b21f6006f2683a9c8fde2ed0090bd9c46b821e Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 02:16:46 +0100 Subject: [PATCH 09/61] New translations parser.qmd (Arabic, Saudi Arabia) --- .../utilities/parser.qmd.ar.qmd | 157 ++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 translations/ar/docs/chapters/functional doc/utilities/parser.qmd.ar.qmd diff --git a/translations/ar/docs/chapters/functional doc/utilities/parser.qmd.ar.qmd b/translations/ar/docs/chapters/functional doc/utilities/parser.qmd.ar.qmd new file mode 100644 index 00000000..19a5227d --- /dev/null +++ b/translations/ar/docs/chapters/functional doc/utilities/parser.qmd.ar.qmd @@ -0,0 +1,157 @@ +# Parser + +this file is responsible for parsing comments in code files. + it extracts various pieces of information such as + description, category, subcategory, link, parameters, return values, + and thrown errors from comments using regular expressions. + + + +## descriptionMatch +`[variable]` + +**Description:** +This method will extract the description from the comments block + + +**Examples:** + +```javascript +Parser.getDescription(comment) => 'This method will extract the description from the comments block' +``` + + + +## categoryMatches +`[variable]` + +**Description:** +This method will extract the category from the comments block + + +**Examples:** + +```javascript +Parser.getCategory(comment) => 'StringUtil' +``` + + + +## subCategoryRegex +`[variable]` + +**Description:** +This method will extract the subcategory from the comments block + + +**Examples:** + +```javascript +Parser.getSubCategory(comment) => 'StringUtil' +``` + + + +## linkRegex +`[variable]` + +**Description:** +This method will extract the link from the comments block + + +**Examples:** + +```javascript +Parser.getLink(comment) => 'StringUtil' +``` + + + +## paramsRegex +`[variable]` + +**Description:** +This method will extract all the params from the comments block + + +**Examples:** + +```javascript +Parser.getParams(comment) => [{name: 'str', type: 'string', description: 'The string to convert to camel case'}] +``` + + + +## moduleRegex +`[variable]` + +**Description:** +This method will extract the module name from the comments block + + +**Examples:** + +```javascript +Parser.getModuleName(comment) => 'StringUtil' +``` + + + +## returnsMatches +`[variable]` + +**Description:** +This method will extract the returns from the comments block + + +**Examples:** + +```javascript +Parser.getReturnsValues(comment) => [{type: 'string', description: 'The string to convert to camel case'}] +``` + + + +## exampleRegex +`[variable]` + +**Description:** +This method will extract the examples from the comments block + + +**Examples:** + +```javascript +Parser.getExamples(comment) => ['StringUtil.convertToCamelCase(\'hello world\') => \'helloWorld\''] +``` + + + +## throwsMatches +`[variable]` + +**Description:** +This method will extract the thrown errors from the comments block + + +**Examples:** + +```javascript +Parser.getThrownErrors(comment) => [{type: 'Error', description: 'The string to convert to camel case'}] +``` + + + +## referencesRegex +`[variable]` + +**Description:** +This method will extract the references from the comments block + + +**Examples:** + +```javascript +Parser.getReferences(comment) => [{text: 'StringUtil', type: 'localModule'}] +``` + From 1714a567f7aa836672c43ba0ab3516d767f751c5 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 02:16:46 +0100 Subject: [PATCH 10/61] New translations writer.qmd (Arabic, Saudi Arabia) --- .../utilities/writer.qmd.ar.qmd | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 translations/ar/docs/chapters/functional doc/utilities/writer.qmd.ar.qmd diff --git a/translations/ar/docs/chapters/functional doc/utilities/writer.qmd.ar.qmd b/translations/ar/docs/chapters/functional doc/utilities/writer.qmd.ar.qmd new file mode 100644 index 00000000..197a1d75 --- /dev/null +++ b/translations/ar/docs/chapters/functional doc/utilities/writer.qmd.ar.qmd @@ -0,0 +1,122 @@ +# Writer + +this typescript module (writer) contains classes and functions + for generating documentation structure and content. + it interacts with various files and directories to organize + documentation chapters, write content to markdown files, + and generate quarto yaml configuration for the documentation book. + + note: this module is not yet complete and is still under development. + + + +## _a +`[variable]` + + + +## unknown +`[other]` + +**Description:** +Formats file names by removing all underscores `(_)` + + + + +## unknown +`[other]` + +**Description:** +This method generates the Quarto YAML configuration file based on the provided chapters. + + + +## _a +`[variable]` + +**Description:** +Creates modules and Categories from tutorials config, these will be required to write them as chapters in the quarto.yml file + + + + + +## unknown +`[function]` + +**Description:** +Copies the content of the tutorials in `/tutorials` to `/docs/chapters/tutorials` + + + + + +## module +`[variable]` + +**Description:** +This method writes the documentation content for a module to a specified file path. + +**Params:** + +| Name | Description | +| --- | --- | +| options | An object containing the module and destination path. | +| options.destinationPath | The destination path where the documentation will be written. | + + + +## categories +`[variable]` + +**Description:** +This method prepares the directory structure for documentation by creating necessary folders and files. + + + +## categories +`[variable]` + +**Description:** +This method writes documentation for each category to a corresponding file within the documentation directory. + + + +## unknown +`[function]` + +**Description:** +This method reads through the tutorials folder and copies them to the destination `/docs` folder, it also + follows the structure of the tutorials set by the `config.json` in the tutorials folder if any + + + + + +## unknown +`[function]` + +**Description:** +This method adds the tutorials as chapters into the _quarto.yml file + + + + + +## configToAdd +`[variable]` + +**Description:** +This method adds the language specs to the _quarto.yml file + + + + + +## docsFolderPath +`[variable]` + +**Description:** +This method creates a copy of each qmd file in the docs folder for each language + From 34a7044dd8598f7d3e33a00736353ad16f43a33e Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 02:16:47 +0100 Subject: [PATCH 11/61] New translations globals.qmd (Arabic, Saudi Arabia) --- .../docs/chapters/globals/globals.qmd.ar.qmd | 76 +++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 translations/ar/docs/chapters/globals/globals.qmd.ar.qmd diff --git a/translations/ar/docs/chapters/globals/globals.qmd.ar.qmd b/translations/ar/docs/chapters/globals/globals.qmd.ar.qmd new file mode 100644 index 00000000..8e7a9a2a --- /dev/null +++ b/translations/ar/docs/chapters/globals/globals.qmd.ar.qmd @@ -0,0 +1,76 @@ +# Globals + +global constructs + + + +## getJSFilesFromDirectory +`[function]` + +**Description:** +This function recursively traverses the specified directory and its subdirectories to find JavaScript files (.js). + It starts by checking each item in the directory. If the item is a directory, it recursively calls itself + to search for JavaScript files within that directory. If the item is a JavaScript file, it adds the file path + to an array of found JavaScript files. + + + + + +## start +`[function]` + +**Description:** +Starts the documentation generation process. + + This function initiates the documentation generation process by performing the following steps: + + 1. It searches for JavaScript files in the specified directory and its subdirectories. + 2. It parses the comments from each JavaScript file using `CommentsUtil.getCommentsFromFile()`. + 3. It processes the comments to extract module information and updates the module and category data structures accordingly. + 4. If a default module is defined, it adds the module and its documentation to the appropriate category or the default category. + 5. It generates the documentation directory and files using the `Writer` utility. + 6. Finally, it logs a message indicating that the documentation generation process is complete. + + This function serves as the entry point for generating documentation for JavaScript files. + + + + + +## unknown +`[other]` + +**Description:** +This method will convert a string to camel toUpperCase + + +**Examples:** + +```javascript +StringUtil.convertToCamelCase('hello world') => 'helloWorld' + StringUtil.convertToCamelCase('hello-world') => 'helloWorld' + StringUtil.convertToCamelCase('hello_world') => 'helloWorld' + StringUtil.convertToCamelCase('helloWorld') => 'helloWorld' + StringUtil.convertToCamelCase('hello') => 'hello' +``` + + + +## unknown +`[other]` + +**Description:** +This method will convert a string to camel toUpperCase + + +**Examples:** + +```javascript +StringUtil.convertToCamelCase('hello world') => 'helloWorld' + StringUtil.convertToCamelCase('hello-world') => 'helloWorld' + StringUtil.convertToCamelCase('hello_world') => 'helloWorld' + StringUtil.convertToCamelCase('helloWorld') => 'helloWorld' + StringUtil.convertToCamelCase('hello') => 'hello' +``` + From b2fef2518e581dfccde90311912dbf3c319a10c7 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 02:16:47 +0100 Subject: [PATCH 12/61] New translations index.qmd (Arabic, Saudi Arabia) --- translations/ar/docs/chapters/globals/index.qmd.ar.qmd | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 translations/ar/docs/chapters/globals/index.qmd.ar.qmd diff --git a/translations/ar/docs/chapters/globals/index.qmd.ar.qmd b/translations/ar/docs/chapters/globals/index.qmd.ar.qmd new file mode 100644 index 00000000..430eb7aa --- /dev/null +++ b/translations/ar/docs/chapters/globals/index.qmd.ar.qmd @@ -0,0 +1,3 @@ +--- +title: Globals +--- From 42aa7d4e033f22ea00824cc1c134726cd1b3ceab Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 02:16:48 +0100 Subject: [PATCH 13/61] New translations changelog.qmd (Arabic, Saudi Arabia) --- .../chapters/tutorials/changelog.qmd.ar.qmd | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 translations/ar/docs/chapters/tutorials/changelog.qmd.ar.qmd diff --git a/translations/ar/docs/chapters/tutorials/changelog.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/changelog.qmd.ar.qmd new file mode 100644 index 00000000..76d282a9 --- /dev/null +++ b/translations/ar/docs/chapters/tutorials/changelog.qmd.ar.qmd @@ -0,0 +1,70 @@ +### Changelog + +--- +title: Change log +--- + + +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## Unreleased (2024-03-05) + +### 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 ✨ + +Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)): + + + + + + + + + + +
Richie
Richie
🚇 🤔 👀
+ + + + + + +This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! + + + +[cc-by]: http://creativecommons.org/licenses/by/4.0/ +[cc-by-image]: https://i.creativecommons.org/l/by/4.0/88x31.png +[cc-by-shield]: https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg?style=flat-square +[forks-shield]: https://img.shields.io/github/forks/Open-Science-Community-Saudi-Arabia/MOOCs.svg?style=flat-square +[forks-url]: https://github.com/Open-Science-Community-Saudi-Arabia/MOOCs/network/members +[stars-shield]: https://img.shields.io/github/stars/Open-Science-Community-Saudi-Arabia/MOOCs.svg?style=flat-square&color=brightgreen +[stars-url]: https://github.com/Open-Science-Community-Saudi-Arabia/MOOCs/stargazers +[issues-shield]: https://img.shields.io/github/issues/Open-Science-Community-Saudi-Arabia/MOOCs.svg?style=flat-square +[issues-url]: https://github.com/Open-Science-Community-Saudi-Arabia/MOOCs/issues + + + + From 82f5200c7e099e5ce1417bcb93a49aec50c06da4 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 02:16:49 +0100 Subject: [PATCH 14/61] New translations improving_documentation.qmd (Arabic, Saudi Arabia) --- .../improving_documentation.qmd.ar.qmd | 220 ++++++++++++++++++ 1 file changed, 220 insertions(+) create mode 100644 translations/ar/docs/chapters/tutorials/contributing/improving_documentation.qmd.ar.qmd diff --git a/translations/ar/docs/chapters/tutorials/contributing/improving_documentation.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/contributing/improving_documentation.qmd.ar.qmd new file mode 100644 index 00000000..f0571fef --- /dev/null +++ b/translations/ar/docs/chapters/tutorials/contributing/improving_documentation.qmd.ar.qmd @@ -0,0 +1,220 @@ +###Improving-documentation + +## Improving Documentation with JSDoc + +### Introduction + +Effective documentation is crucial for maintaining a clear and understandable codebase. One powerful tool for enhancing documentation within your code is JSDoc. JSDoc is a markup language that allows you to annotate your code with structured comments, enabling automatic generation of documentation. In this guide, we will explore the uses of JSDoc and how it can improve your project's documentation. + +### Using JSDoc for Genereated Documentation + +One of the primary uses of JSDoc is to generate documentation directly from your codebase. By adding JSDoc comments to your functions, classes, and variables, you can provide essential information that is automatically extracted and transformed into comprehensive documentation. + +To use JSDoc for generating documentation, follow these steps: + +1. Markup Comments: Add JSDoc comments directly above the code elements you want to document. Use the /\*_ ... _/ syntax to indicate a JSDoc comment block. + +2. Documenting Functions: Use JSDoc tags to describe function parameters, return values, and additional information. Tags like @param, @returns, and @description are commonly used for this purpose. Other important custom tags are @category and @subcategory, these tags help to structure the generated documentation into chapters. All modules under a `subcategory` will be under one chapter, the chapter name will correspond to the name assigned to the `subcategory`. + The main idea around @category and @subcategory is to allow nested chapters for example one parent chapter A can have other subchapters (Chapter Aa, Chapter Ab, Chapter Ac) with each of these subchapters having their individual modules. + Note that this is only two levels of nesting, with Chapter A being the @category and the @subcategory will be the other chapters. Initially we intend to implement 2 levels of nested chapters but this as at the time of writing this quarto only allows 1 levels of nesting (i.e, you can only have 1 parent chapter with no subChapters, as a result, only the @subcategories will be displayed as chapters in the rendered document. + +3. Documenting Classes: For classes, use JSDoc comments to provide descriptions, document class properties, and document class methods. Tags like @class, @property, and @method are commonly used in this context. + +4. Running JSDoc Generation: Use a JSDoc generator tool, such as JSDoc itself or other popular tools like TypeDoc or JSDoc3, to parse your codebase and generate the documentation output. Configure the generator to target the desired output format, such as HTML or Markdown. + +5. Review and Update: Review the generated documentation and ensure it accurately represents your code. Update the JSDoc comments as needed to provide clearer explanations or additional information. + +For more information on using JSDoc for generating documentation, see the [JSDoc documentation](https://jsdoc.app/) or [Getting started with JSDoc](https://jsdoc.app/about-getting-started.html). + +### Using JSDoc for Writing Documentation + +JSDoc can also be used beyond generating code documentation. Its flexible syntax and tagging system make it a valuable tool for writing other aspects of your project's documentation, such as tutorials, guides, and reference materials. + +To use JSDoc for writing documentation, consider the following approaches: + +1. Tutorials and Guides: Utilize JSDoc comments to write step-by-step tutorials and guides within your codebase. By embedding tutorial content in JSDoc comments, you can keep the documentation closely tied to the relevant code, making it easier for developers to follow along and understand the concepts. + +2. Inline Examples: Use JSDoc comments to include inline code examples that demonstrate the usage of functions, classes, or modules. These examples can serve as both instructional material and a quick reference for developers. + +3. Reference Materials: JSDoc comments can be used to provide additional information in reference materials, such as explaining design patterns, outlining best practices, or clarifying complex concepts. Leverage JSDoc tags like @example or @see to link to relevant resources or code examples. + +4. Integration with Markdown: JSDoc supports Markdown within comments, allowing you to incorporate formatted text, headings, lists, and other Markdown features into your documentation. This enables you to create more visually appealing and structured content within your JSDoc comments. + +### Improving JSQuarto documentation with JSDoc + + +The JSQuarto documentation is not yet complete. There are several areas that could be improved, including: + +- More detailed explanations of the JSQuarto project structure and codebase +- Additional information on how to contribute to the project +- Implementing JSQuarto as a CLI tool +- Additional information on how to maintain the JSQuarto project +- Additional information on how to deploy the JSQuarto project +- Project roadmap and future plans + +To improve the JSQuarto documentation, you can use JSDoc to add additional documentation directly within the codebase. This will allow you to provide more detailed explanations of the code and project structure, as well as additional information on how to contribute to the project, how to use the JSQuarto API, and how to maintain and deploy the project. As at the time of writing this, the documentation was built with other packages to improve the User interface, one of which is [Better-docs](https://github.com/SoftwareBrothers/better-docs). + +### Tutorials guide + +This section provides an overview of the `config.json` files used in the JSQuarto documentation, specifically focusing on the `tutorials` folder. The `config.json` file serve as configuration files that help structure and organize the documentation, while the `tutorials` folder contains the Markdown files for various tutorials. + +#### The `tutorials` Folder + +The `tutorials` folder within the documentation directory is dedicated to hosting tutorials on various topics related to the JSQuarto platform. This folder contains a collection of Markdown files, each representing an individual tutorial. + +Markdown is a lightweight markup language that allows for easy formatting and structuring of text, making it ideal for creating tutorials. Markdown files provide a simple yet powerful way to document step-by-step instructions, code examples, explanations, and other relevant information. + +The `tutorials` folder can be organized into subfolders to further categorize and group related tutorials. This helps users easily locate and access the tutorials they need based on their specific interests or requirements. + +By structuring tutorials within the `tutorials` folder using Markdown, contributors can contribute new tutorials, update existing ones, and ensure that the documentation remains comprehensive and user-friendly. + +Overall, the combination of `.json` files and the `tutorials` folder enables a well-organized and accessible documentation structure, allowing users to navigate and explore the JSQuarto platform documentation with ease. + +#### Overview of `config.json` Files + +The `config.json` file in the JSQuarto documentation play a crucial role in organizing and categorizing the content. This file define the structure of the documentation and provide metadata for each section, tutorial, or topic. They allow maintainers and contributors to easily navigate and manage the documentation by specifying titles, creating nested structures, and linking related topics. + +By using `config.json` file, the documentation can be dynamically generated and updated based on the defined structure. This makes it easier to maintain consistency, track changes, and add new content. + + +#### The `.json` configuration +Let's explain how this structure works by looking at the `config.json` file in the `tutorials /` folder. This file defines the structure of the tutorials section of the documentation, including the titles, descriptions links for each tutorial. + +```json +{ + "changelog": { + "title": "Changelog" + }, + "environment_setup": { + "title": "Environment Setup" + }, + "contributing": { + "title": "Contributing" + } +} +``` + +In this example, the `.json` file defines the titles and relationships of the main sections within your documentation. The sections are represented as objects, with each object having a unique key and a `"title"` key-value pair. +1. "changelog" represents the "Changelog" section. The `"title"` key-value pair specifies the title of this section as "Changelog." + +2. "environment_setup" represents the "Environment Setup" section. The `"title"` key-value pair specifies the title of this section as "Environment Setup." + +3. "contributing" represents the "Contributing" section. The `"title"` key-value pair specifies the title of this section as "Contributing." + +With this structure, your documentation folder will contain separate Markdown files for each section, named according to the keys in the `.json` file. For example: + +```yaml +- `documentation /` + - `docs /` + - `changelog.md` + - `environment_setup.md` + - `contributing.md` + - `tutorials.json` +``` + +Each Markdown file will correspond to a section in your documentation and should contain the relevant content for that section. + +This simplified structure allows you to organize your documentation into distinct sections, making it easier for readers to locate and access the specific topics they need. It provides a clear and concise way to represent the main sections of your documentation without the need for nested tutorials or complex hierarchies. + +Remember to update the `.json` file whenever you add or modify sections to ensure that the documentation structure accurately reflects the content of your documentation. + +By following this structure, you can maintain a well-organized and easily navigable documentation repository. + +#### Nested `.json` configuration for tutorials +To structure tutorials and create nested tutorials within your documentation, you can use the `.json` file to define the hierarchy and relationships between tutorials. Here's an example of how you can structure tutorials using a `.json` file: + +```yaml +{ + "maintainers": { + "title": "Technical guide for Maintainers", + "children": { + "reviewing_pr": { + "title": "Reviewing pull requests" + }, + "ci_workflow": { + "title": "CI Workflow" + }, + "secrets_and_security": { + "title": "Secret Access/Management" + }, + "deployment_guide": { + "title": "Deployment Guide" + } + } + }, + "contributing": { + "title": "Contributing to the project", + "children": { + "adding_a_course": { + "title": "Adding a course" + }, + "api_project_structure": { + "title": "API project structure" + }, + "improving_documentation": { + "title": "Improving documentation" + }, + "project_structure": { + "title": "Project structure" + }, + "raising_issues": { + "title": "Raising issues" + }, + "raising_pr": { + "title": "Raising pull requests" + } + } + }, + "review": { + "title": "Reviewing the project" + } +} + ``` + +In this example, the `.json` file represents a documentation structure with two main sections: "Technical guide for Maintainers" and "Technical guide for API developers". Each section has its own set of tutorials represented as nested objects. + +1. Define the main sections or categories as top-level objects within the `.json` file, such as "maintainers" and "contributing". + +2. Within each main section, provide a `"title"` key to specify the title or heading for that section. For example, "Technical guide for Maintainers" and "Technical guide for API developers". + +3. Add a `"children"` key within each main section to define the nested tutorials. Each tutorial is represented as a child object within the `"children"` object. Not all tutorials may have children tutorials, an example of this is the `review` tutorial. Since it has no children the program will only look for a `review.qmd` file and not a `review` folder + +4. For each tutorial, provide a unique key as the object's key, such as "reviewing_pr" and "ci_workflow". + +5. Within each tutorial object, include a `"title"` key to specify the title or heading for that specific tutorial. + +For this example here is what the folder structure would look like assuming the root folder is `tutorials /`: + +```yaml + - tutorials/ + - maintainers/ + - maintainers.qmd + - reviewing_pr.qmd + - ci_workflow.qmd + - secrets_and_security.qmd + - deployment_guide.qmd + + - contributing/ + - api.md + - api_structure.md + - api_authentication_flow.qmd + - jwt_token_management.qmd + - rbac_handler_flow.qmd + + - review.qmd + + - config.json +``` + +In this structure: + +- The `.json` configuration file is located in the `tutorials/` folder +- The `tutorials` folder contains subfolders representing different sections or categories of tutorials. +- Each section or category folder, such as `maintainers` and `contributing`, contains the `.qmd` files for individual tutorials. + + +The nested structure allows you to organize tutorials hierarchically, making it easier to navigate and find specific tutorials based on their topic or category. + +It's important to note that the tutorial structure allows only one level of nesting. This means you can have main sections and their respective tutorials, but you cannot create further nested folders within the tutorials. + +By following this folder structure and accompanying `.qmd` overview files, you can easily define the hierarchy and relationships between tutorials, allowing you to create nested tutorials and organize your documentation in a logical and structured manner. From 71289c61cae3c013297e27bdd9ba975d14f849ff Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 02:16:49 +0100 Subject: [PATCH 15/61] New translations raising_issues.qmd (Arabic, Saudi Arabia) --- .../contributing/raising_issues.qmd.ar.qmd | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 translations/ar/docs/chapters/tutorials/contributing/raising_issues.qmd.ar.qmd diff --git a/translations/ar/docs/chapters/tutorials/contributing/raising_issues.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/contributing/raising_issues.qmd.ar.qmd new file mode 100644 index 00000000..f22b94f5 --- /dev/null +++ b/translations/ar/docs/chapters/tutorials/contributing/raising_issues.qmd.ar.qmd @@ -0,0 +1,45 @@ +###Raising-issues + + +Raising issues is an essential part of contributing to an open source project. Before you start, it's recommended that you have a basic understanding of Markdown and GitHub, which are commonly used in this workflow. Markdown is a lightweight markup language that is used to format and style text on the web. You can find a comprehensive guide to [Markdown](https://guides.github.com/features/mastering-markdown/) on the GitHub website + +If you're not familiar with GitHub, it's a web-based platform that provides tools for version control, code management, and collaboration. GitHub provides a step-by-step guide to getting started with their platform on their [website](https://guides.github.com/activities/hello-world/) + +It's important to check whether your idea or issue has already been raised by someone else. You can do this by searching through the project's existing issues on GitHub. If you find an issue that is similar to yours, please comment on it to let others know that you're also interested in working on it. + +If the issue has already been closed, or if it only partially solves your problem, it's recommended that you open a new issue with a reference to the old one. This can help to keep the discussion organized and ensure that all relevant information is easily accessible. + +Remember, raising an issue is an opportunity to improve the project and contribute to the open source community. With a little bit of effort and attention to detail, you can help make a real difference + +### Issue templates +We have issue templates for different types of issues. Please use the appropriate template for your issue. If you're not sure which template to use, please use the `General` template. + +- General template ([preview](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/blob/main/.github/ISSUE_TEMPLATE/ISSUE_TEMPLATE.md)) : This is the default template for raising an issue. Use this template if you're not sure which template to use. +- Bug report template ([preview](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/blob/.github/ISSUE_TEMPLATE/bug_report.md)) : Use this template to report a bug or problem with the project. +- New feature Request template ([preview](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/blob/.github/ISSUE_TEMPLATE/new_course.md)) : Use this template to request permission to add a new course to the list. + + +### Writing a clear title and description +When opening an issue, it's important to write a clear and concise title that accurately reflects the problem or suggestion you want to raise. The title should be descriptive enough so that others can quickly understand the issue, but not too long or complicated. + +In the issue description, provide as much detail as possible about the issue or suggestion. Include steps to reproduce the problem if applicable, and any relevant information or context that can help others understand the issue better. + +### Using Issue labels +Issue labels are used to categorize and organize issues in an open source project. They can help contributors quickly identify the type and status of an issue, and can also help maintainers prioritize and manage the project's backlog of issues. + +When raising an issue, make sure to choose the appropriate label(s) that best describes the issue. For example, if you're reporting a bug, you might use the "bug" label. If you're suggesting a new feature or improvement, you might use the "enhancement" label. + +Some common issue labels you might see in a GitHub project include: + +* Bug: Used to report an error or problem with the code or functionality of the project. +* Enhancement: Used to suggest a new feature or improvement to the project. +* Documentation: Used to suggest changes or improvements to the project's documentation. +* Help wanted: Used to indicate that the project maintainers are actively seeking contributions to help resolve the issue. +* Good first issue: Used to indicate that the issue is suitable for new contributors who are just getting started with the project. + +### Contributing to issue discussions +If you're interested in working on an issue, please leave a comment to let others know. This will help to avoid duplicate work and ensure that the issue is assigned to the right person. +Once you've opened an issue or commented on an existing one, it's important to actively participate in the discussion. This means responding to comments and questions from others, providing additional information or clarification if needed, and being open to feedback and suggestions. + +### Conclusion +Raising issues is an important part of contributing to open source projects. By following these guidelines, you can help ensure that your issue is clear, well-documented, and easy for others to understand. Remember to actively participate in discussions, follow up on issues, and contribute code if you're able to. With a little effort and collaboration, we can all help make open source projects better for everyone. From 3dbbd79469352f388e0470fe5d4e741da9449eff Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 02:16:50 +0100 Subject: [PATCH 16/61] New translations raising_pr.qmd (Arabic, Saudi Arabia) --- .../contributing/raising_pr.qmd.ar.qmd | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 translations/ar/docs/chapters/tutorials/contributing/raising_pr.qmd.ar.qmd diff --git a/translations/ar/docs/chapters/tutorials/contributing/raising_pr.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/contributing/raising_pr.qmd.ar.qmd new file mode 100644 index 00000000..113548bf --- /dev/null +++ b/translations/ar/docs/chapters/tutorials/contributing/raising_pr.qmd.ar.qmd @@ -0,0 +1,52 @@ +###Raising-pr + +## Introduction +A pull request is a way for contributors to submit changes to a project maintained by others. The changes are proposed and then reviewed and potentially merged by the project maintainers. In this guide, we will walk you through the steps of making a pull request to the Open-Science-Community-Saudi-Arabia/JSquarto repository on GitHub. + +## Steps +1. Find a feature or bug that you want to work on. +2. Fork the Open-Science-Community-Saudi-Arabia/JSquarto repository to your GitHub account. +3. Clone the forked repository on your local machine. + + ```bash + git clone https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto + ``` + +4. Sync the fork, to avoid merge conflicts. + + ```bash + git remote add upstream https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto + git fetch upstream + git pull upstream main + git push + ``` + +5. Create a new branch with your GitHub username as its name. + + ```bash + git checkout -b + ``` +It is not mandatory to name the new branch with your GitHub username, but it is a good practice to do so, as long as the name of the branch is clear and concise, you can name it whatever you want. + +6. Make your changes on this new branch. +7. Commit your changes with a clear commit message. + + ```bash + git add . + git commit -m "Clear and concise commit message" + ``` + +8. Push your changes to your forked repository. + + ```bash + git push origin + ``` + +9. Go to the [Open-Science-Community-Saudi-Arabia/JSquarto](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto) repository on GitHub, and you should see a message suggesting to create a new pull request. Click on it. +10. To raise the PR choose the PR template and fill it with the required information. The PR template is a set of questions that you need to answer to make it easier for the maintainers to review your pull request. you can find the PR template [here](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/blob/main/.github/PULL_REQUEST_TEMPLATE.md) + +11. Add a clear and concise title and description for your pull request, explaining the changes you made. + +12. Submit your pull request, and wait for the maintainers to review your changes. + +Congratulations! You've just made a pull request to the Open-Science-Community-Saudi-Arabia/JSquarto repository. From 9e4052f69a53db4307f5d21aa83996409d948dd9 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 02:16:51 +0100 Subject: [PATCH 17/61] New translations environment_setup.qmd (Arabic, Saudi Arabia) --- .../tutorials/environment_setup.qmd.ar.qmd | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 translations/ar/docs/chapters/tutorials/environment_setup.qmd.ar.qmd diff --git a/translations/ar/docs/chapters/tutorials/environment_setup.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/environment_setup.qmd.ar.qmd new file mode 100644 index 00000000..e6c41bde --- /dev/null +++ b/translations/ar/docs/chapters/tutorials/environment_setup.qmd.ar.qmd @@ -0,0 +1,75 @@ +### Environment_setup + +--- +title: 'Environment Setup' +--- + +#### Prerequisites (#environment-setup) +Before testing the tool locally, ensure you have the following prerequisites installed on your system: +- Node.js and npm (Node Package Manager) +- Git (optional, if cloning the repository) + +#### Installation +To test the tool locally, follow these steps: + +1. Clone the repository: + + ```bash + git clone https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto + ``` +2. Navigate to the projecte directory + +3. Install dependencies + + ```bash + npm install + ``` + +### Running the Tool +Once the dependencies are installed, you can paste the files in the JS files or folder in the `/source_files` directory you can run the tool using the following command + +1. To generate the documentation run the following command + + ```bash + npm run doc:generate + ``` + + This will extract the JSDoc comments from the js files and write them to their corresponding Quarto Markdown files. + + You can choose to specify the directory where the `source_files` are, to do this run + + ```bash + npm run doc:generate --source= + ``` + + It also supports addition of custom tutorials, to do this add the .qmd files for the tutorials in the `/tutorials` directory + + The generated `.qmd` files can be found in the `/docs/chapters` folder + + This command may vary depending on the workflow you choose, you may want to create the docs files in other languages too. To do this you can run the command below + + ```bash + npm run doc:generate languages=en,ar,es include_localized_versions --source= + ``` + + This will generate the documentation in English, Arabic and Spanish. You can add more languages by separating them with a comma. (This doesn't actually translate the documentation, it just creates a copy of the documentation and renames it to the specified language). To integrate with a translation service, you can use the [Crowdin](https://crowdin.com/) service. + + For more information on the available workflows see the guide here @sec-workflows + + +2. To preview the generated documentation run + + ```bash + npm run doc:preview + ``` + + The docs are previewed with quarto, so make sure to have quarto already installed + + +3. You can choose to generate and preview in one go, to do this run the command below + + ```bash + npm run build --source= + ``` + + This will generate the documentation, preview with quarto and open a link to preview the docs From 297016c4f3aedeea033444fb3e4ddca7440201bc Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 02:16:51 +0100 Subject: [PATCH 18/61] New translations adding_tutorials.qmd (Arabic, Saudi Arabia) --- .../how_to/adding_tutorials.qmd.ar.qmd | 89 +++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 translations/ar/docs/chapters/tutorials/how_to/adding_tutorials.qmd.ar.qmd diff --git a/translations/ar/docs/chapters/tutorials/how_to/adding_tutorials.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/how_to/adding_tutorials.qmd.ar.qmd new file mode 100644 index 00000000..8b934f22 --- /dev/null +++ b/translations/ar/docs/chapters/tutorials/how_to/adding_tutorials.qmd.ar.qmd @@ -0,0 +1,89 @@ +###Adding-tutorials + +### Tutorials +Tutorials are a great way to teach people how to use your project. They are a step-by-step guide that walks the user through a specific task or concept. Tutorials are a great way to get people up and running with your project, and to help them understand how to use it. + +### How tutorials are written +Tutorials are written in Quarto markdown. Quarto is a markdown language that is designed to be easy to write and read, and to be easy to convert to other formats. Quarto is a superset of markdown, so any markdown file is a valid quarto file. Quarto adds a few features to markdown to make it easier to write tutorials. Some of the features include: + +- The ability to include code and output in the same file +- The ability to include code from other files +- Adding metadata / images and other content to the file + + +### Folder to write the tutorial +By default, tutorials are written in the `/tutorials` folder. This is the folder where all the tutorials are stored. Each tutorial is stored in a separate folder, and the folder name is the name of the tutorial. Inside the folder, there are serveral `.qmd` files that contains the tutorial contents. + + +### Configuring the tutorial +There is also a `config.json` file that contains the configuration for the tutorial. The `config.json` file is used to structure how the tutorial is displayed in terms of the order of the tutorial, the title, the description, and the grouping of the tutorial. + +Below is an example of a `config.json` file: + +```json +{ + "contributing": { + "title": "Contributing to the project", + "children": { + "improving_documentation": { + "title": "Improving documentation" + }, + "raising_issues": { + "title": "Raising issues" + }, + "raising_pr": { + "title": "Raising pull requests" + } + } + }, + "project_structure": { + "title": "Project structure" + }, + "environment_setup": { + "title": "Environment Setup" + }, + "changelog": { + "title": "Change log" + }, + "localization": { + "title": "Localization" + }, + "how_to": { + "title": "How to's", + "children": { + "setting_default_readme": { + "title": "Setting default README" + }, + "adding_tutorials": { + "title": "Adding tutorials" + }, + "specifying_source_files": { + "title": "Specifying source files" + }, + "starting_a_new_build": { + "title": "Starting a new build" + } + } + } +} + +``` + +In the example above, the `config.json` file contains a list of tutorials and the order in which they should be displayed. The `config.json` file also contains the title of the tutorial and the description of the tutorial. + +The `config.json` file also contains a list of children for each tutorial. This is used to group tutorials together. For example, in the example above, the `contributing` tutorial has three children: `improving_documentation`, `raising_issues`, and `raising_pr`. This groups the three tutorials together under the `contributing` tutorial. + +### Grouping tutorials +Tutorials can be grouped together using the `config.json` file. This is useful for organizing tutorials into categories. For example, you might want to group all the tutorials related to contributing to the project together, or all the tutorials related to setting up the environment together. This makes it easier for users to find the tutorials they are interested in. + +In the example above, the `config.json` file groups the tutorials into categories such as `contributing`, `project_structure`, `environment_setup`, `changelog`, `localization`, and `how_to`. Each of these categories contains a list of tutorials, and each tutorial contains a list of children. This allows you to organize the tutorials in a way that makes sense for your project. + +In this tutorial, we learned how to write tutorials in Quarto markdown, and how to configure the `config.json` file to structure how the tutorial is displayed. We also learned how to group tutorials together using the `config.json` file. This allows you to organize the tutorials in a way that makes sense for your project, and makes it easier for users to find the tutorials they are interested in. + +Summary + - How tutorials are written + - Format for writing tutorials + - How to write a tutorial + - Folder to write the tutorial + + From 66432eb37fa0e8b8314ba3738ffcbf10bb90fdb4 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 02:16:52 +0100 Subject: [PATCH 19/61] New translations starting_the_project.qmd (Arabic, Saudi Arabia) --- .../how_to/starting_the_project.qmd.ar.qmd | 115 ++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 translations/ar/docs/chapters/tutorials/how_to/starting_the_project.qmd.ar.qmd diff --git a/translations/ar/docs/chapters/tutorials/how_to/starting_the_project.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/how_to/starting_the_project.qmd.ar.qmd new file mode 100644 index 00000000..da3aa1be --- /dev/null +++ b/translations/ar/docs/chapters/tutorials/how_to/starting_the_project.qmd.ar.qmd @@ -0,0 +1,115 @@ +###Starting-the-project + +### Starting the project environment + +Before you start, make sure you have the following installed on your machine: +- [Quarto](https://quarto.org/docs/get-started/index.html) +- [Node.js](https://nodejs.org/en/download/) +- [Yarn](https://yarnpkg.com/getting-started/install) or [NPM](https://www.npmjs.com/get-npm) +- [Typescript](https://www.typescriptlang.org/download) (optional - Only required if the files you're working with are in typescript) + + +### Steps +1. Environment Setup + Refer to environment setup guide for more details [See here](#environment-setup) + +2. For cases where you are working with a project that uses typescript, you will need to compile the typescript files to javascript. To do this, run the following command in the terminal: + ```bash + tsc -b + ``` + + Make sure to direct the transpiled files to the correct directory. You can do this by updating the `tsconfig.json` file to include the `outDir` property. For example: + ```json + { + "compilerOptions": { + "outDir": "./dist" + } + } + ``` + +3. Start the project + ```bash + yarn run build + ``` + + OR + + ```bash + npm run build + ``` + + This command will command will generate the documentation and also start a local quarto server. You can access the documentation by visiting the http link shown on your terminal. + +4. Make changes to the documentation and see the changes reflect on the browser. + +5. Once you are done, you can stop the server by pressing `Ctrl + C` on your terminal. + +6. To generate the documentation without starting the server, run the following command: + ```bash + npm run doc:generate + ``` + + OR + + ```bash + yarn run doc:generate + ``` +9: To preview the documentation without starting the server, run the following command: + ```bash + npm run doc:preview + ``` + + OR + + ```bash + yarn run doc:preview + ``` + + This command will startup a quarto server to preview the already generated documentation and open it in your default browser. + +8. To clean the generated documentation, run the following command: + ```bash + npm run doc:clean + ``` + + OR + + ```bash + yarn run doc:clean + ``` + + This command will delete the generated documentation files. Note that this command will not delete the `/tutorials` or `/source_files directory or wherever the tutorials and source_files are stored. Only the generated documentation files will be deleted. + + + +You can specify the source files path by including the `--source` flag in the command. For example: +```bash +npm run build --source=./path/to/source_files +``` + +OR + +```bash +yarn run build --source=./path/to/source_files +``` + +You can also specify the tutorials path by including the `--tutorial` flag in the command. For example: +```bash +npm run build --tutorials=./path/to/tutorials +``` + + +Summary of commands: +- `npm run build` - Generate the documentation and start a local quarto server +- `yarn run build` - Generate the documentation and start a local quarto server +- `npm run doc:generate` - Generate the documentation without starting the server +- `yarn run doc:generate` - Generate the documentation without starting the server +- `npm run doc:preview` - Preview the generated documentation without starting the server +- `yarn run doc:preview` - Preview the generated documentation without starting the server +- `npm run doc:clean` - Delete the generated documentation files +- `yarn run doc:clean` - Delete the generated documentation files + +Tags +- `--source` - Specify the source files path +- `--tutorial` - Specify the tutorials path + From 52415a59093a1cbc5859c50da191a82f17655423 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 02:16:53 +0100 Subject: [PATCH 20/61] New translations usage.qmd (Arabic, Saudi Arabia) --- .../tutorials/how_to/usage.qmd.ar.qmd | 69 +++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 translations/ar/docs/chapters/tutorials/how_to/usage.qmd.ar.qmd diff --git a/translations/ar/docs/chapters/tutorials/how_to/usage.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/how_to/usage.qmd.ar.qmd new file mode 100644 index 00000000..9a917d27 --- /dev/null +++ b/translations/ar/docs/chapters/tutorials/how_to/usage.qmd.ar.qmd @@ -0,0 +1,69 @@ +###Usage + +## Usage {#sec-usage} + +### Custom CLI arguments +The CLI arguments are used to customize the behavior of the JSquarto tool. These bespoke arguments enable you to tailor the documentation generation process to suit your specific requirements. By leveraging these arguments, you can enhance the efficiency and effectiveness of the documentation generation process, thereby streamlining your workflow and optimizing your documentation output. + +Some of the custom CLI arguments supported by JSquarto include: +1. `--source`: Source files are pivotal components containing the comments that JSquarto utilizes to generate comprehensive documentation. Specifies the directory containing the source files to be documented. These files can be can be written in various languages supported by JSquarto, such as JavaScript, TypeScript, and JSX. By default, JSquarto will check for the `/source_files` 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. + +2. `--tutorial`: Specifies the directory containing the tutorial files to be included in the documentation. This argument allows you to incorporate tutorial content into your documentation, providing additional context and guidance for users. + +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`: Specifies the languages to be supported in the documentation. This argument enables you to generate documentation in multiple languages, catering to a diverse user base. For example, `languages=en,fr,es` specifies English, French, and Spanish as the supported languages. + +5. `include_localized_versions`: Specifies whether to include localized versions of the generated documentation. For example, if specified, JSquarto will generate seperate files for each specified language. + +### Configuration +The `config.json` file in the root directory of the project is used to store the configuration settings for the JSquarto tool. This file contains the default settings for the documentation generation process, such as the source files directory, tutorial files directory, output directory, and supported languages. You can modify these settings to customize the documentation generation process according to your preferences. This file is useful for cases where the cli arguments specified are multiple and you want to avoid specifying them each time you run the tool. + +The `config.json` file contains the following fields: +1. `sourceDirectory`: Specifies the directory containing the source files to be documented. By default, this field is set to `/source_files` within the project structure. This is the same as the `--source` CLI argument. + +2. `tutorialDirectory`: Specifies the directory containing the tutorial files to be included in the documentation. By default, this field is set to `/tutorial_files` within the project structure. This is the same as the `--tutorial` CLI argument. + +3. `outputDirectory`: Specifies the output directory where the generated documentation will be stored. By default, this field is set to `/docs` within the project structure. This is the same as the `--output` CLI argument. + + +### Usage +To utilize these custom CLI arguments, simply append them to the JSquarto command when executing the tool. For example: + +To specify the source files directory: +```bash +npm run doc:generate --source=/path/to/your/source/files +``` + +To specify the tutorial files directory: +```bash +npm run doc:generate --tutorial=/path/to/your/tutorial/files +``` + +To specify the output directory: +```bash +npm run doc:generate --output=/path/to/your/output/directory +``` + +To specify the supported languages: +```bash +npm run doc:generate languages=en,fr,es +``` +This will only add the languages to the config file (_quarto.yml) and not generate the documentation in the specified languages. This is important for cases where an external tool like Crowdin will be used to translate the documentation and generate the files in the specified languages. + +To include localized versions of the generated documentation: +```bash +npm run doc:generate include_localized_versions languages=en,fr,es +``` +This will generate the documentation in the specified languages and also add the languages to the config file (_quarto.yml). + +Note: If you intend to `include_localized_versions`, you must also specify the `languages` argument to indicate the supported languages for the documentation. + +By leveraging these custom CLI arguments, you can tailor the documentation generation process to meet your specific needs and preferences, thereby enhancing the quality and usability of your documentation output. + + +### Leveraging TypeScript in Source Files +When utilizing TypeScript within your project, it's advisable to transpile your TypeScript source files into JavaScript before initiating the JSquarto process. This recommendation stems from the fact that JSquarto lacks intrinsic support for TypeScript syntax. Once you've transpiled your TypeScript files into JavaScript, you can seamlessly execute JSquarto on the resultant JavaScript files to generate comprehensive documentation. + +Integrating TypeScript Transpilation +Prior to executing JSquarto, ensure to transpile your TypeScript source files into JavaScript using your preferred transpiler, such as TypeScript Compiler (tsc). This step ensures compatibility with JSquarto's documentation generation process, thereby facilitating a smooth and efficient From 145338dd2f6e932fdc2ca05ed23d6bb5a9e1dcee Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 02:16:53 +0100 Subject: [PATCH 21/61] New translations workflows.qmd (Arabic, Saudi Arabia) --- .../tutorials/how_to/workflows.qmd.ar.qmd | 104 ++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 translations/ar/docs/chapters/tutorials/how_to/workflows.qmd.ar.qmd diff --git a/translations/ar/docs/chapters/tutorials/how_to/workflows.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/how_to/workflows.qmd.ar.qmd new file mode 100644 index 00000000..dd89f16b --- /dev/null +++ b/translations/ar/docs/chapters/tutorials/how_to/workflows.qmd.ar.qmd @@ -0,0 +1,104 @@ +###Workflows + +### Workflows {#sec-workflows} +There are different workflows that can be adopted to optimize the documentation generation process using JSquarto. + +1. Doc generation +2. Doc generation with manual transalation +3. Doc generation with crowdin translation + +### Doc generation +This workflow involves generating documentation in a single language. The process is straightforward and involves executing JSquarto on the source files to generate comprehensive documentation in the specified language. This workflow is ideal for projects targeting a specific language audience and seeking to streamline the documentation generation process. + +#### STEPS +1. To do this, simply execute the JSquarto command with the desired custom CLI arguments, such as `--source` and `languages`, to specify the source files directory and supported languages, respectively. For example: + + ```bash + npm run doc:generate --source=/path/to/your/source/files + ``` + +### Doc generation with manual translation +For manual translation of the documentation, you can generate the documentation in multiple languages and then manually translate the content into the desired languages. For this workflow, we use [babelquarto](https://docs.ropensci.org/babelquarto/) which helps to preview the documentation in multiple languages. Although this doesn't translate the content, it provides a preview of the documentation in the specified languages, enabling you to manually translate the content. + +#### Steps +1. Generate the documentation in multiple languages using JSquarto with the `languages` argument to specify the supported languages. For example: + + ```bash + npm run doc:generate languages=en,fr,es include_localized_versions --source=/path/to/your/source/files + ``` +Note: Ensure to include the `include_localized_versions` argument to generate copies of the documentation in the specified languages. If they are not included, only the default language documentation will be generated. But the languages config will only be added to the config (_quarto.yml) file. + +2. Manually translate the content in the generated documentation files for each language. You can leverage tools such as Google Translate or professional translation services to facilitate the translation process. + +3. Download RStudio and install the `babelquarto` package from CRAN. This package is used to preview the documentation in multiple languages. You can install the package using the following command: + + ```R + install.packages('babelquarto', repos = c('https://ropensci.r-universe.dev', 'https://cloud.r-project.org')) + ``` + +4. Open the generated doc folder in RStudio, navigate to the console and set the working directory to the doc folder. + + ```R + project_dir <- "/home/richie/Desktop/repos/oscsa/JSquarto/docs" + ``` + +5. Preview the documentation in multiple languages using the `babelquarto` package. For example, to preview the documentation in English, French, and Spanish, execute the following command: + + ```R + babelquarto::render_book(file.path(parent_dir, project_dir)) + ``` +6. As at the time of writing this, there are minor issues with navigating the previewed documentation in different languages. To fix this temporarily, run + + ```bash + npm run fix:all languages=en,fr,es + ``` + + Note: The `fix:all` script is a custom script that fixes the navigation issues in the previewed documentation. This script is used to update the navigation links in the previewed documentation to enable seamless navigation between the different languages. And the languages specified in the script should match the languages specified in the `languages` argument during the documentation generation process. + +7. You can navigate to the `/docs/_book` directory to view the previewed documentation in multiple languages. The previewed documentation provides a comprehensive overview of the content in each language, enabling you to verify the translations and ensure the accuracy and quality of the documentation. + + + +### Doc generation with crowdin translation +For automated translation of the documentation, you can leverage the Crowdin platform to facilitate the translation process. Crowdin is a cloud-based translation management platform that enables you to automate the translation of content into multiple languages. By integrating Crowdin with JSquarto, you can streamline the translation process and generate comprehensive documentation in various languages efficiently. + +#### Steps +1. Generate the documentation in multiple languages using JSquarto with the `languages` argument to specify the supported languages. For example: + + ```bash + npm run doc:generate languages=en,fr,es --source=/path/to/your/source/files + ``` + + Note that the `include_localized_versions` argument is not required for this workflow, as Crowdin will handle the translation process. And generate the different files for each language. + +2. Integrate Crowdin with JSquarto to automate the translation process. To integrate Crowdin, you need to create a Crowdin project and configure the project settings to enable the automatic translation of the documentation. You can refer to the [Crowdin Github integration documentation](https://support.crowdin.com/github-integration/#:~:text=Open%20your%20project%20and%20go%20to%20the%20Integrations,drop-down%20list%20to%20integrate%20via%20your%20GitHub%20account) for detailed instructions on setting up a project and configuring the translation settings. +On Crowdin, you can set up how the translated files will be named, make sure it follows the format `original_file_name.locale.extension` e.g `index.en.qmd`, `index.fr.qmd`, `index.es.qmd` + +3. Once you've configured the Crowdin project settings, you can proceed to render the documentation in multiple languages using the `babelquarto` package. This step enables you to preview the documentation in different languages before initiating the translation process. You can leverage the `babelquarto` package to preview the documentation in multiple languages, as described in the previous workflow. To do this open the generated doc folder in RStudio, navigate to the console and set the working directory to the doc folder. + + ```R + project_dir <- "/home/richie/Desktop/repos/oscsa/JSquarto/docs" + ``` + + Preview the documentation in multiple languages using the `babelquarto` package. For example, to preview the documentation in English, French, and Spanish, execute the following command: + + ```R + babelquarto::render_book(file.path(parent_dir, project_dir)) + ``` + +4. After rendering the book, the html files will be generated and set in the `/docs/_book` directory. You can then serve the book using any static server like `http-server` or `live-server` to preview the documentation in multiple languages. Alternatively, you can run the following command to serve the book: + + ```bash + npm run serve + ``` + + After serving the book, you can navigate to the specified URL to view the documentation in multiple languages. In some cases you may notice that the navigation links are not working as expected. To fix this, run the following command: + + ```bash + npm run fix:all languages=en,fr,es + ``` + +This workflow uses JSquarto to generate the documentation, and Crowdin to initiate the translation process which creates the translated files in the specified languages, lastly the `babelquarto` package to preview the documentation in multiple languages. + + + From 78bb7d9047081fc7dd2dc04067e3627ee20ecf7f Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 02:16:54 +0100 Subject: [PATCH 22/61] New translations localization.qmd (Arabic, Saudi Arabia) --- .../tutorials/localization.qmd.ar.qmd | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 translations/ar/docs/chapters/tutorials/localization.qmd.ar.qmd diff --git a/translations/ar/docs/chapters/tutorials/localization.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/localization.qmd.ar.qmd new file mode 100644 index 00000000..563c07c5 --- /dev/null +++ b/translations/ar/docs/chapters/tutorials/localization.qmd.ar.qmd @@ -0,0 +1,48 @@ +### Localization + +--- +title: Localization +--- + +Localization is the process of adapting software to meet the language, cultural, and other specific requirements of a particular locale or market. It is an essential aspect of software development that helps to ensure that products are accessible to users around the world. Localization involves translating software content such as user interfaces, text, and multimedia, among others, to make it appropriate for different regions. + +Crowdin is a powerful localization platform that provides a range of features for efficient software localization. In this section, we will discuss localization, translation, and how Crowdin works as a localization platform. We will also highlight the importance of localization in software development and how it can impact the success of a product. Finally, we will explore the benefits of using Crowdin as a localization platform and the advantages it offers compared to other alternatives. + +## What is Localization? + +Localization is the process of adapting a product or service to meet the language, cultural, and other requirements of a specific country or region. This involves translating the content of the product, such as text, images, and audio, into the local language and adapting it to meet the cultural requirements of the target market. + +Localization is important in software development because it helps to make the product more accessible to a global audience and improve user experience. By translating the content into the local language, developers can reach a wider audience and make it easier for users to understand and use the product. + +## What is Translation? + +Translation is the process of converting written or spoken content from one language to another. This process involves understanding the original content and reproducing it in the target language, while taking into account any cultural or linguistic differences. + +Translation is important in software development because it allows developers to make their products accessible to a global audience. By translating the content into the local language, developers can reach a wider audience and make it easier for users to understand and use the product. + +## Crowdin as a Localization Platform + +Crowdin is a localization platform that helps developers to manage the localization process for their products. It provides a range of features that make it easier for developers to translate their products and collaborate with translators. + +Crowdin features include: + +- Translation management +- Collaboration tools +- Quality assurance +- Integration with development tools +- Crowdsourcing +- In-context translations +- Machine translation + +Using Crowdin for localization has several advantages, including: + +- Easier management of translation projects +- Faster turnaround times for translations +- Improved translation quality +- Collaboration with translators from around the world +- Integration with development tools, such as GitHub and Bitbucket +- Ability to use machine translation for faster translations + +## Conclusion + +Localization is an important aspect of software development, and using a platform like Crowdin can help make the process easier and more efficient. With Crowdin, developers can manage translation projects, collaborate with translators, and improve the quality of translations. By using a combination of localization and translation, developers can make their products more accessible to a global audience and improve user experience. From d2d9ca65325c148e3d06d4fb18a912b1cce92843 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 02:16:55 +0100 Subject: [PATCH 23/61] New translations project_structure.qmd (Arabic, Saudi Arabia) --- .../tutorials/project_structure.qmd.ar.qmd | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 translations/ar/docs/chapters/tutorials/project_structure.qmd.ar.qmd diff --git a/translations/ar/docs/chapters/tutorials/project_structure.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/project_structure.qmd.ar.qmd new file mode 100644 index 00000000..0bcc3272 --- /dev/null +++ b/translations/ar/docs/chapters/tutorials/project_structure.qmd.ar.qmd @@ -0,0 +1,47 @@ +### Project_structure + +--- +title: Project structure +--- + + +#### Project file structure +JSQuarto is structured as follows: + +```bash +├── src +│ ├── intefaces +│ │ ├── index.ts +│ ├── utils +│ │ ├── codeconstruct.ts +│ │ ├── component.ts +│ │ ├── file.ts +│ │ ├── logger.ts +│ │ ├── parser.ts +│ │ ├── string.ts +│ │ ├── writer.ts +│ ├── tutorials +│ │ ├── contributing/ +│ │ ├── how_to/ +│ │ ├── environment_setup.qmd +│ │ ├── localization.qmd +│ │ ├── project_structure.qmd +│ │ ├── config.json +│ │ +│ ├── index.ts +│ │ +│ ├── package.json +│ ├── package-lock.json +│ ├── .prettierrc + +``` + + +The `API` directory contains the source code for JSQuarto. The `API` directory is structured as follows: + +- `src/interfaces` - Contains the all type/intefaces definitions for the project. +- `src/utils` - Contains the all utility functions for the project. These utility functions are used to perform various tasks such as parsing, writing, and logging. +- `src/tutorials` - Contains the all tutorials for the project. These tutorials are written in Quarto Markdown format. Note that the `config.json` file is used to define how the tutorials are structured. +- `src/index.ts` - The main entry point for the project. +- `src/package.json` - The project's package.json file. +- `src/.prettierrc` - The project's prettier configuration file. From 12a09d37e3be3b3c906fe53c264e10fa66b5dd0b Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 02:16:55 +0100 Subject: [PATCH 24/61] New translations index.md (Arabic, Saudi Arabia) --- translations/ar/docs/index.md.ar.md | 33 +++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 translations/ar/docs/index.md.ar.md diff --git a/translations/ar/docs/index.md.ar.md b/translations/ar/docs/index.md.ar.md new file mode 100644 index 00000000..3d2d939e --- /dev/null +++ b/translations/ar/docs/index.md.ar.md @@ -0,0 +1,33 @@ +# Welcome to JSQuarto Documentation + +## About + +JSQuarto is a tool designed to generate JavaScript package API reference documentation using Markdown and Quarto. It serves as an alternative to JSDoc, providing a simpler and more flexible approach for documenting JavaScript code. + +## Purpose + +The purpose of JSQuarto is to streamline the process of generating API reference documentation for JavaScript packages. By leveraging Markdown and Quarto, developers can easily create and maintain comprehensive documentation for their JavaScript projects. + +## Inspiration + +JSQuarto draws inspiration from various documentation tools and methodologies, including:
+ +- [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 is committed to supporting localization and translation of generated documentation. We are planning to integrate Crowdin, a localization management platform, to facilitate translation efforts. This will enable users to present the generated QMD files in multiple languages, making documentation accessible to a wider audience. + +## Contributing Organization + +JSQuarto is developed and maintained by the [Open Science Community Saudi Arabia](https://github.com/Open-Science-Community-Saudi-Arabia). Our mission is to promote open science practices and foster collaboration among researchers and developers in Saudi Arabia. + +## Getting Started + +To start using JSQuarto, visit the [GitHub repository](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto) for installation instructions and usage documentation. + +## Feedback and Support + +If you have any questions, feedback, or need support, please [open an issue](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/issues) on GitHub or [join our community](https://github.com/Open-Science-Community-Saudi-Arabia) for assistance. From edad44db1cccd2ce6602e30fab4cac4abf7a1d1f Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 04:13:52 +0100 Subject: [PATCH 25/61] New translations index.qmd (Arabic, Saudi Arabia) --- translations/ar/docs/chapters/functional doc/index.qmd.ar.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/translations/ar/docs/chapters/functional doc/index.qmd.ar.qmd b/translations/ar/docs/chapters/functional doc/index.qmd.ar.qmd index 9cfe7567..d04f2db0 100644 --- a/translations/ar/docs/chapters/functional doc/index.qmd.ar.qmd +++ b/translations/ar/docs/chapters/functional doc/index.qmd.ar.qmd @@ -1,3 +1,3 @@ --- -title: Functional doc +العنوان: وثيقة وظيفية --- From 6463f3a03e16bce26d7b4ba2038e41a3c6860ca8 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 04:13:53 +0100 Subject: [PATCH 26/61] New translations commentsutil.qmd (Arabic, Saudi Arabia) --- .../utilities/commentsutil.qmd.ar.qmd | 36 +++++++++---------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/translations/ar/docs/chapters/functional doc/utilities/commentsutil.qmd.ar.qmd b/translations/ar/docs/chapters/functional doc/utilities/commentsutil.qmd.ar.qmd index d044077f..e5a415df 100644 --- a/translations/ar/docs/chapters/functional doc/utilities/commentsutil.qmd.ar.qmd +++ b/translations/ar/docs/chapters/functional doc/utilities/commentsutil.qmd.ar.qmd @@ -1,18 +1,18 @@ -# Commentsutil +#تعليقسوتيل -this file provides utility classes for parsing and extracting information - from comments within code files. it includes methods to identify and - extract metadata from both module and non-module comments, - facilitating better documentation and understanding of code constructs - such as functions, variables, classes, and modules. +يوفر هذا الملف فئات فائدة لتحليل المعلومات واستخراجها + من التعليقات داخل ملفات التعليمات البرمجية. ويتضمن طرقًا لتحديد و + استخراج البيانات الوصفية من تعليقات الوحدة وغير الوحدة، + تسهيل التوثيق بشكل أفضل وفهم بنيات التعليمات البرمجية + مثل الوظائف والمتغيرات والفئات والوحدات النمطية. -## moduleName -`[variable]` +## اسم وحدة +`[متغير]` -**Description:** -This method extracts module block information from comments, including module name, description, category, subcategory, link, and references. +**وصف:** +تستخرج هذه الطريقة معلومات كتلة الوحدة من التعليقات، بما في ذلك اسم الوحدة والوصف والفئة والفئة الفرعية والرابط والمراجع. **Params:** @@ -23,9 +23,9 @@ This method extracts module block information from comments, including module na ## description -`[variable]` +`[متغير]` -**Description:** +**وصف:** This method extracts other block information from comments, including description, params, link, examples, returns, thrown errors, and references. **Params:** @@ -37,9 +37,9 @@ This method extracts other block information from comments, including descriptio ## fileContent -`[variable]` +`[متغير]` -**Description:** +**وصف:** This method retrieves comments from a source file using Acorn parser. **Params:** @@ -53,7 +53,7 @@ This method retrieves comments from a source file using Acorn parser. ## unknown `[other]` -**Description:** +**وصف:** This class represents a comment extracted from a source file. **Params:** @@ -68,7 +68,7 @@ This class represents a comment extracted from a source file. ## unknown `[function]` -**Description:** +**وصف:** This method sets the construct information of the comment, including the type and name of the construct. **Params:** @@ -82,7 +82,7 @@ This method sets the construct information of the comment, including the type an ## unknown `[other]` -**Description:** +**وصف:** This method retrieves module block information from the comment using the CommentsUtil class. @@ -90,6 +90,6 @@ This method retrieves module block information from the comment using the Commen ## unknown `[other]` -**Description:** +**وصف:** This method retrieves other block information from the comment using the CommentsUtil class. From df024527f9f18b9a513cc027ec79bbf8a359747d Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 04:13:54 +0100 Subject: [PATCH 27/61] New translations components.qmd (Arabic, Saudi Arabia) --- .../utilities/components.qmd.ar.qmd | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/translations/ar/docs/chapters/functional doc/utilities/components.qmd.ar.qmd b/translations/ar/docs/chapters/functional doc/utilities/components.qmd.ar.qmd index 31921ad8..9d45332e 100644 --- a/translations/ar/docs/chapters/functional doc/utilities/components.qmd.ar.qmd +++ b/translations/ar/docs/chapters/functional doc/utilities/components.qmd.ar.qmd @@ -8,7 +8,7 @@ this module is used to generate the quarto yml file ## recursivelyConvertAllStringValuesInObjectToLowerCase `[function]` -**Description:** +**وصف:** Recursively convert all string values in an object to lowercase @@ -39,7 +39,7 @@ const obj = { ## unknown `[other]` -**Description:** +**وصف:** Add a document to the module @@ -69,7 +69,7 @@ const module = new Module({ name: 'StringUtil' }); ## unknown `[other]` -**Description:** +**وصف:** Get the documents in the module @@ -105,7 +105,7 @@ const module = new Module({ name: 'StringUtil' }); ## unknown `[other]` -**Description:** +**وصف:** sets the source file path @@ -114,7 +114,7 @@ sets the source file path ## unknown `[other]` -**Description:** +**وصف:** Add a module to the subcategory @@ -124,7 +124,7 @@ Add a module to the subcategory ## unknown `[other]` -**Description:** +**وصف:** Get the modules in the subcategory @@ -134,7 +134,7 @@ Get the modules in the subcategory ## unknown `[other]` -**Description:** +**وصف:** Get the name of the subcategory @@ -148,7 +148,7 @@ Get the name of the subcategory ## unknown `[other]` -**Description:** +**وصف:** This class represents a category. **Params:** @@ -162,7 +162,7 @@ This class represents a category. ## unknown `[other]` -**Description:** +**وصف:** Adds a subcategory to the category. **Params:** @@ -176,7 +176,7 @@ Adds a subcategory to the category. ## unknown `[other]` -**Description:** +**وصف:** Retrieves the subcategories in the category. @@ -184,7 +184,7 @@ Retrieves the subcategories in the category. ## unknown `[other]` -**Description:** +**وصف:** Retrieves the name of the category. @@ -192,7 +192,7 @@ Retrieves the name of the category. ## unknown `[other]` -**Description:** +**وصف:** Adds a module to the category. **Params:** @@ -206,6 +206,6 @@ Adds a module to the category. ## unknown `[other]` -**Description:** +**وصف:** Retrieves the modules in the category. From abaad425aafb431f35b9c40538012defafb541ca Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 04:13:54 +0100 Subject: [PATCH 28/61] New translations constructidentifier.qmd (Arabic, Saudi Arabia) --- .../utilities/constructidentifier.qmd.ar.qmd | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/translations/ar/docs/chapters/functional doc/utilities/constructidentifier.qmd.ar.qmd b/translations/ar/docs/chapters/functional doc/utilities/constructidentifier.qmd.ar.qmd index 8dbd7459..5081fc0c 100644 --- a/translations/ar/docs/chapters/functional doc/utilities/constructidentifier.qmd.ar.qmd +++ b/translations/ar/docs/chapters/functional doc/utilities/constructidentifier.qmd.ar.qmd @@ -14,7 +14,7 @@ the class called constructidentifier, contains methods to identify different typ ## unknown `[function]` -**Description:** +**وصف:** Retrieves the name of the module construct from a given line of code. @@ -30,7 +30,7 @@ Retrieves the name of the module construct from a given line of code. ## variableX `[function]` -**Description:** +**وصف:** Retrieves the name of the function construct from a given line of code. @@ -44,7 +44,7 @@ Retrieves the name of the function construct from a given line of code. ## variableRegex -`[variable]` +`[متغير]` **Params:** @@ -55,9 +55,9 @@ Retrieves the name of the function construct from a given line of code. ## classRegex -`[variable]` +`[متغير]` -**Description:** +**وصف:** Retrieves the name of the class construct from a given line of code. @@ -73,7 +73,7 @@ Retrieves the name of the class construct from a given line of code. ## declarationconst `[function]` -**Description:** +**وصف:** Identifies the type of construct (function, variable, class, module, other) from the given code text. @@ -89,7 +89,7 @@ Identifies the type of construct (function, variable, class, module, other) from ## unknown `[function]` -**Description:** +**وصف:** Retrieves the name of the construct from the given code text. From 23700649d465373063fe4fd2bd9cd9c50ba5031c Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 04:13:55 +0100 Subject: [PATCH 29/61] New translations file.qmd (Arabic, Saudi Arabia) --- .../ar/docs/chapters/functional doc/utilities/file.qmd.ar.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/translations/ar/docs/chapters/functional doc/utilities/file.qmd.ar.qmd b/translations/ar/docs/chapters/functional doc/utilities/file.qmd.ar.qmd index 8038ddcb..6bd3ea6b 100644 --- a/translations/ar/docs/chapters/functional doc/utilities/file.qmd.ar.qmd +++ b/translations/ar/docs/chapters/functional doc/utilities/file.qmd.ar.qmd @@ -13,7 +13,7 @@ this module is used to read and write files ## unknown `[other]` -**Description:** +**وصف:** This method returns the type and name of the code construct linked to a comment From a911234806126104b87060b5dd17da1eb76ac877 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 04:13:56 +0100 Subject: [PATCH 30/61] New translations parser.qmd (Arabic, Saudi Arabia) --- .../utilities/parser.qmd.ar.qmd | 40 +++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/translations/ar/docs/chapters/functional doc/utilities/parser.qmd.ar.qmd b/translations/ar/docs/chapters/functional doc/utilities/parser.qmd.ar.qmd index 19a5227d..9a93cf27 100644 --- a/translations/ar/docs/chapters/functional doc/utilities/parser.qmd.ar.qmd +++ b/translations/ar/docs/chapters/functional doc/utilities/parser.qmd.ar.qmd @@ -8,9 +8,9 @@ this file is responsible for parsing comments in code files. ## descriptionMatch -`[variable]` +`[متغير]` -**Description:** +**وصف:** This method will extract the description from the comments block @@ -23,9 +23,9 @@ Parser.getDescription(comment) => 'This method will extract the description from ## categoryMatches -`[variable]` +`[متغير]` -**Description:** +**وصف:** This method will extract the category from the comments block @@ -38,9 +38,9 @@ Parser.getCategory(comment) => 'StringUtil' ## subCategoryRegex -`[variable]` +`[متغير]` -**Description:** +**وصف:** This method will extract the subcategory from the comments block @@ -53,9 +53,9 @@ Parser.getSubCategory(comment) => 'StringUtil' ## linkRegex -`[variable]` +`[متغير]` -**Description:** +**وصف:** This method will extract the link from the comments block @@ -68,9 +68,9 @@ Parser.getLink(comment) => 'StringUtil' ## paramsRegex -`[variable]` +`[متغير]` -**Description:** +**وصف:** This method will extract all the params from the comments block @@ -83,9 +83,9 @@ Parser.getParams(comment) => [{name: 'str', type: 'string', description: 'The st ## moduleRegex -`[variable]` +`[متغير]` -**Description:** +**وصف:** This method will extract the module name from the comments block @@ -98,9 +98,9 @@ Parser.getModuleName(comment) => 'StringUtil' ## returnsMatches -`[variable]` +`[متغير]` -**Description:** +**وصف:** This method will extract the returns from the comments block @@ -113,9 +113,9 @@ Parser.getReturnsValues(comment) => [{type: 'string', description: 'The string t ## exampleRegex -`[variable]` +`[متغير]` -**Description:** +**وصف:** This method will extract the examples from the comments block @@ -128,9 +128,9 @@ Parser.getExamples(comment) => ['StringUtil.convertToCamelCase(\'hello world\') ## throwsMatches -`[variable]` +`[متغير]` -**Description:** +**وصف:** This method will extract the thrown errors from the comments block @@ -143,9 +143,9 @@ Parser.getThrownErrors(comment) => [{type: 'Error', description: 'The string to ## referencesRegex -`[variable]` +`[متغير]` -**Description:** +**وصف:** This method will extract the references from the comments block From 01ce910e8562282b5608669db51fa5f7923050de Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 04:13:57 +0100 Subject: [PATCH 31/61] New translations writer.qmd (Arabic, Saudi Arabia) --- .../utilities/writer.qmd.ar.qmd | 36 +++++++++---------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/translations/ar/docs/chapters/functional doc/utilities/writer.qmd.ar.qmd b/translations/ar/docs/chapters/functional doc/utilities/writer.qmd.ar.qmd index 197a1d75..77e5b654 100644 --- a/translations/ar/docs/chapters/functional doc/utilities/writer.qmd.ar.qmd +++ b/translations/ar/docs/chapters/functional doc/utilities/writer.qmd.ar.qmd @@ -11,14 +11,14 @@ this typescript module (writer) contains classes and functions ## _a -`[variable]` +`[متغير]` ## unknown `[other]` -**Description:** +**وصف:** Formats file names by removing all underscores `(_)` @@ -27,15 +27,15 @@ Formats file names by removing all underscores `(_)` ## unknown `[other]` -**Description:** +**وصف:** This method generates the Quarto YAML configuration file based on the provided chapters. ## _a -`[variable]` +`[متغير]` -**Description:** +**وصف:** Creates modules and Categories from tutorials config, these will be required to write them as chapters in the quarto.yml file @@ -45,7 +45,7 @@ Creates modules and Categories from tutorials config, these will be required to ## unknown `[function]` -**Description:** +**وصف:** Copies the content of the tutorials in `/tutorials` to `/docs/chapters/tutorials` @@ -53,9 +53,9 @@ Copies the content of the tutorials in `/tutorials` to `/docs/chapters/tutorials ## module -`[variable]` +`[متغير]` -**Description:** +**وصف:** This method writes the documentation content for a module to a specified file path. **Params:** @@ -68,17 +68,17 @@ This method writes the documentation content for a module to a specified file pa ## categories -`[variable]` +`[متغير]` -**Description:** +**وصف:** This method prepares the directory structure for documentation by creating necessary folders and files. ## categories -`[variable]` +`[متغير]` -**Description:** +**وصف:** This method writes documentation for each category to a corresponding file within the documentation directory. @@ -86,7 +86,7 @@ This method writes documentation for each category to a corresponding file withi ## unknown `[function]` -**Description:** +**وصف:** This method reads through the tutorials folder and copies them to the destination `/docs` folder, it also follows the structure of the tutorials set by the `config.json` in the tutorials folder if any @@ -97,7 +97,7 @@ This method reads through the tutorials folder and copies them to the destinatio ## unknown `[function]` -**Description:** +**وصف:** This method adds the tutorials as chapters into the _quarto.yml file @@ -105,9 +105,9 @@ This method adds the tutorials as chapters into the _quarto.yml file ## configToAdd -`[variable]` +`[متغير]` -**Description:** +**وصف:** This method adds the language specs to the _quarto.yml file @@ -115,8 +115,8 @@ This method adds the language specs to the _quarto.yml file ## docsFolderPath -`[variable]` +`[متغير]` -**Description:** +**وصف:** This method creates a copy of each qmd file in the docs folder for each language From 5e7b7e0cc3745861ac6fb1ee82cd438bdbb0cceb Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 04:13:57 +0100 Subject: [PATCH 32/61] New translations globals.qmd (Arabic, Saudi Arabia) --- translations/ar/docs/chapters/globals/globals.qmd.ar.qmd | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/translations/ar/docs/chapters/globals/globals.qmd.ar.qmd b/translations/ar/docs/chapters/globals/globals.qmd.ar.qmd index 8e7a9a2a..0a3a6aa2 100644 --- a/translations/ar/docs/chapters/globals/globals.qmd.ar.qmd +++ b/translations/ar/docs/chapters/globals/globals.qmd.ar.qmd @@ -7,7 +7,7 @@ global constructs ## getJSFilesFromDirectory `[function]` -**Description:** +**وصف:** This function recursively traverses the specified directory and its subdirectories to find JavaScript files (.js). It starts by checking each item in the directory. If the item is a directory, it recursively calls itself to search for JavaScript files within that directory. If the item is a JavaScript file, it adds the file path @@ -20,7 +20,7 @@ This function recursively traverses the specified directory and its subdirectori ## start `[function]` -**Description:** +**وصف:** Starts the documentation generation process. This function initiates the documentation generation process by performing the following steps: @@ -41,7 +41,7 @@ Starts the documentation generation process. ## unknown `[other]` -**Description:** +**وصف:** This method will convert a string to camel toUpperCase @@ -60,7 +60,7 @@ StringUtil.convertToCamelCase('hello world') => 'helloWorld' ## unknown `[other]` -**Description:** +**وصف:** This method will convert a string to camel toUpperCase From b00119b7a92e8153f5953a3889ba06ef4bef9107 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 14:26:32 +0100 Subject: [PATCH 33/61] New translations commentsutil.qmd (Arabic, Saudi Arabia) --- .../utilities/commentsutil.qmd.ar.qmd | 46 +++++++++---------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/translations/ar/docs/chapters/functional doc/utilities/commentsutil.qmd.ar.qmd b/translations/ar/docs/chapters/functional doc/utilities/commentsutil.qmd.ar.qmd index e5a415df..e1c8ba32 100644 --- a/translations/ar/docs/chapters/functional doc/utilities/commentsutil.qmd.ar.qmd +++ b/translations/ar/docs/chapters/functional doc/utilities/commentsutil.qmd.ar.qmd @@ -16,80 +16,80 @@ **Params:** -| Name | Description | + الاسم الوصف | --- | --- | -| comments | The comments to extract module block information from. | + تعليقات التعليقات لاستخراج معلومات كتلة الوحدة النمطية منها. | -## description +## وصف `[متغير]` **وصف:** -This method extracts other block information from comments, including description, params, link, examples, returns, thrown errors, and references. +تستخرج هذه الطريقة معلومات كتلة أخرى من التعليقات، بما في ذلك الوصف، والمشارجات، والربط، والأمثلة، والإرجاع، والأخطاء التي ألقيت والمراجع. **Params:** -| Name | Description | + الاسم الوصف | --- | --- | -| comments | The comments to extract other block information from. | + تعليقات التعليقات لاستخراج معلومات كتلة أخرى منها. | -## fileContent +## محتوى الملف `[متغير]` **وصف:** -This method retrieves comments from a source file using Acorn parser. +تسترجع هذه الطريقة التعليقات من ملف مصدر باستخدام Acorn parser. **Params:** -| Name | Description | + الاسم الوصف | --- | --- | -| sourceFile | The source file to retrieve comments from. | + مصدر الملف مصدر الملف لاسترداد التعليقات منه. | -## unknown +## غير معروف `[other]` **وصف:** -This class represents a comment extracted from a source file. +يمثل هذا الصف تعليقا مستخرجا من ملف مصدر. **Params:** -| Name | Description | + الاسم الوصف | --- | --- | -| text | The text content of the comment. | -| endLocation | The end location of the comment. | + النص محتوى النص للتعليق. | + الموقع النهائي الموقع النهائي للتعليق. | -## unknown +## غير معروف `[function]` **وصف:** -This method sets the construct information of the comment, including the type and name of the construct. +وتحدد هذه الطريقة المعلومات التجميعية للتعليق، بما في ذلك نوع واسم البناء. **Params:** -| Name | Description | + الاسم الوصف | --- | --- | -| info | The construct information to set. | + معلومات معلومات البناء التي يجب تعيينها. | -## unknown +## غير معروف `[other]` **وصف:** -This method retrieves module block information from the comment using the CommentsUtil class. +هذه الطريقة تسترجع معلومات الوحدة النمطية من التعليق باستخدام صف التعليقات. -## unknown +## غير معروف `[other]` **وصف:** -This method retrieves other block information from the comment using the CommentsUtil class. +تسترجع هذه الطريقة معلومات كتلة أخرى من التعليق باستخدام صف التعليقات. From e02dce15bb23c35154944db4e1e7e791bc95edf0 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 14:26:33 +0100 Subject: [PATCH 34/61] New translations components.qmd (Arabic, Saudi Arabia) --- .../utilities/components.qmd.ar.qmd | 142 +++++++++--------- 1 file changed, 71 insertions(+), 71 deletions(-) diff --git a/translations/ar/docs/chapters/functional doc/utilities/components.qmd.ar.qmd b/translations/ar/docs/chapters/functional doc/utilities/components.qmd.ar.qmd index 9d45332e..453b5af1 100644 --- a/translations/ar/docs/chapters/functional doc/utilities/components.qmd.ar.qmd +++ b/translations/ar/docs/chapters/functional doc/utilities/components.qmd.ar.qmd @@ -1,211 +1,211 @@ -# Components +# المكونات -this module is used to generate the quarto yml file +يتم استخدام هذه الوحدة لتوليد ملف الـ quarto yml -## recursivelyConvertAllStringValuesInObjectToLowerCase +## متكررًا yConvertAllStringValuesInObjectToLowerCase `[function]` **وصف:** -Recursively convert all string values in an object to lowercase +تحويل جميع قيم السلسلة بشكل متكرر في كائن إلى أحرف صغيرة -**Examples:** +**أمثلة:** -```javascript +```جافا سكريبت const obj = { - name: 'Hello World', - description: 'This is a description', + الاسم: "مرحبا بالعالم"، + الوصف: "هذا وصف"، blockInfo: { - name: 'Hello World', - description: 'This is a description', + الاسم: "مرحبا بالعالم"، + الوصف: "هذا وصف"، }, }; - recursivelyConvertAllStringValuesInObjectToLowerCase(obj); + متكررًا ConvertAllStringValuesInObjectToLowerCase(obj)؛ // => { - // name: 'hello world', - // description: 'this is a description', + // الاسم: 'مرحبا بالعالم', + // الوصف: "هذا وصف"، // blockInfo: { - // name: 'hello world', - // description: 'this is a description', + // الاسم: 'مرحبا بالعالم', + // الوصف: "هذا وصف"، // }, // } ``` -## unknown +## غير معروف `[other]` **وصف:** -Add a document to the module +إضافة مستند إلى الوحدة -**Examples:** +**أمثلة:** -```javascript -const module = new Module({ name: 'StringUtil' }); - const moduleDoc = new ModuleDoc({ - originalFilePath: 'string.ts', - data: { +```جافا سكريبت +الوحدة النمطية = وحدة جديدة({ name: 'StringUtil' })؛ + وحدة نمطية = وحدة جديدة ({ + الأصل: 'سلسلة.ts', + البيانات: { blockInfo: { - name: 'StringUtil', - description: 'This class contains methods for manipulating strings', + الاسم: 'StringUtil', + الوصف: "يحتوي هذا الفصل على أساليب لمعالجة السلاسل"، }, - constructInfo: { - type: 'class', - name: 'StringUtil', + بناء المعلومات: { + النوع: 'صنف'، + الاسم: 'StringUtil', }, }, }); - module.addDoc(moduleDoc); + module.addDoc(moduleDoc)؛ ``` -## unknown +## غير معروف `[other]` **وصف:** -Get the documents in the module +احصل على المستندات في الوحدة -**Examples:** +**أمثلة:** -```javascript -const module = new Module({ name: 'StringUtil' }); - const moduleDoc = new ModuleDoc({ - originalFilePath: 'string.ts', - data: { +```جافا سكريبت +الوحدة النمطية = وحدة جديدة({ name: 'StringUtil' })؛ + وحدة نمطية = وحدة جديدة ({ + الأصل: 'سلسلة.ts', + البيانات: { blockInfo: { - name: 'StringUtil', - description: 'This class contains methods for manipulating strings', + الاسم: 'StringUtil', + الوصف: "يحتوي هذا الفصل على أساليب لمعالجة السلاسل"، }, - constructInfo: { - type: 'class', - name: 'StringUtil', + بناء المعلومات: { + النوع: 'صنف'، + الاسم: 'StringUtil', }, }, }); - module.addDoc(moduleDoc); + module.addDoc(moduleDoc)؛ module.getDocs(); // => [ModuleDoc] ``` -## unknown +## غير معروف `[other]` -## unknown +## غير معروف `[other]` **وصف:** -sets the source file path +تعيين مسار الملف المصدر -## unknown +## غير معروف `[other]` **وصف:** -Add a module to the subcategory +إضافة وحدة إلى الفئة الفرعية -## unknown +## غير معروف `[other]` **وصف:** -Get the modules in the subcategory +الحصول على الوحدات في الفئة الفرعية -## unknown +## غير معروف `[other]` **وصف:** -Get the name of the subcategory +احصل على اسم الفئة الفرعية -## Category +## فئة `[class]` -## unknown +## غير معروف `[other]` **وصف:** -This class represents a category. +هذا الصف يمثل فئة. **Params:** -| Name | Description | + الاسم الوصف | --- | --- | -| name | The name of the category. | + الاسم اسم الفئة. | -## unknown +## غير معروف `[other]` **وصف:** -Adds a subcategory to the category. +يضيف فئة فرعية إلى الفئة. **Params:** -| Name | Description | + الاسم الوصف | --- | --- | -| subCategory | The subcategory to add. | + الفئة الفرعية الفئة الفرعية المراد إضافتها. | -## unknown +## غير معروف `[other]` **وصف:** -Retrieves the subcategories in the category. +يسترجع الفئات الفرعية في الفئة. -## unknown +## غير معروف `[other]` **وصف:** -Retrieves the name of the category. +يسترد اسم الفئة. -## unknown +## غير معروف `[other]` **وصف:** -Adds a module to the category. +يضيف وحدة إلى الفئة. **Params:** -| Name | Description | + الاسم الوصف | --- | --- | -| module | The module to add. | + الوحدة النمطية الوحدة المراد إضافتها. | -## unknown +## غير معروف `[other]` **وصف:** -Retrieves the modules in the category. +يسترجع الوحدات النمطية في الفئة. From 33d58e7295cdac6debf58b23ea32973a69d57172 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 14:26:34 +0100 Subject: [PATCH 35/61] New translations constructidentifier.qmd (Arabic, Saudi Arabia) --- .../utilities/constructidentifier.qmd.ar.qmd | 48 +++++++++---------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/translations/ar/docs/chapters/functional doc/utilities/constructidentifier.qmd.ar.qmd b/translations/ar/docs/chapters/functional doc/utilities/constructidentifier.qmd.ar.qmd index 5081fc0c..6a33fcf2 100644 --- a/translations/ar/docs/chapters/functional doc/utilities/constructidentifier.qmd.ar.qmd +++ b/translations/ar/docs/chapters/functional doc/utilities/constructidentifier.qmd.ar.qmd @@ -1,8 +1,8 @@ # Constructidentifier -the class called constructidentifier, contains methods to identify different types of code constructs - (such as functions, variables, classes, and modules) within a line of code. - these methods help in extracting and determining the names associated with each construct type. +الفصل المسمى بناء، يحتوي على طرق لتحديد أنواع مختلفة من التركيبات البرمجية + (مثل الدوال والمتغيرات والفصول والوحدات) ضمن سطر من الكود. + وتساعد هذه الأساليب في استخراج وتحديد الأسماء المرتبطة بكل نوع من أنواع البناء. @@ -11,19 +11,19 @@ the class called constructidentifier, contains methods to identify different typ -## unknown +## غير معروف `[function]` **وصف:** -Retrieves the name of the module construct from a given line of code. +يسترجع اسم وحدة بناء من سطر معين من التعليمات البرمجية. **Params:** -| Name | Description | + الاسم الوصف | --- | --- | -| line | The line of code to parse. | + السطر سطر التعليمات البرمجية إلى التحليل. | @@ -31,26 +31,26 @@ Retrieves the name of the module construct from a given line of code. `[function]` **وصف:** -Retrieves the name of the function construct from a given line of code. +يسترجع اسم بناء الدالة من سطر معين من الكود. **Params:** -| Name | Description | + الاسم الوصف | --- | --- | -| line | The line of code to parse. | + السطر سطر التعليمات البرمجية إلى التحليل. | -## variableRegex +## متغير ريجكس `[متغير]` **Params:** -| Name | Description | + الاسم الوصف | --- | --- | -| line | The line of code to parse. | + السطر سطر التعليمات البرمجية إلى التحليل. | @@ -58,45 +58,45 @@ Retrieves the name of the function construct from a given line of code. `[متغير]` **وصف:** -Retrieves the name of the class construct from a given line of code. +يسترجع اسم بناء الصف الدراسي من سطر معين من الكود. **Params:** -| Name | Description | + الاسم الوصف | --- | --- | -| line | The line of code to parse. | + السطر سطر التعليمات البرمجية إلى التحليل. | -## declarationconst +## إعلان `[function]` **وصف:** -Identifies the type of construct (function, variable, class, module, other) from the given code text. +يحدد نوع البناء (الدالة، المتغير، الصف، الوحدة، أخرى) من نص الرمز المحدد. **Params:** -| Name | Description | + الاسم الوصف | --- | --- | -| text | The code text to analyze. | + النص النص البرمجي لتحليله. | -## unknown +## غير معروف `[function]` **وصف:** -Retrieves the name of the construct from the given code text. +يسترجع اسم البناء من نص الكود المعين. **Params:** -| Name | Description | + الاسم الوصف | --- | --- | -| text | The code text to analyze. | + النص النص البرمجي لتحليله. | From 69c92ab4929740229844f1d49c65881347dbd93d Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 14:26:35 +0100 Subject: [PATCH 36/61] New translations file.qmd (Arabic, Saudi Arabia) --- .../functional doc/utilities/file.qmd.ar.qmd | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/translations/ar/docs/chapters/functional doc/utilities/file.qmd.ar.qmd b/translations/ar/docs/chapters/functional doc/utilities/file.qmd.ar.qmd index 6bd3ea6b..95e8f423 100644 --- a/translations/ar/docs/chapters/functional doc/utilities/file.qmd.ar.qmd +++ b/translations/ar/docs/chapters/functional doc/utilities/file.qmd.ar.qmd @@ -1,34 +1,34 @@ -# File +# ملف -this module is used to read and write files +يتم استخدام هذه الوحدة النمطية لقراءة وكتابة الملفات - this file reads and analyzes source code files. - it identifies the type and name of the code construct linked - to a given comment by examining the lines following the comment, - utilizing the constructidentifier class. + هذا الملف يقرأ ويحلل ملفات الكود المصدري. + يحدد نوع واسم بناء الرمز المرتبط + على تعليق معين عن طريق دراسة الخطوط التالية للتعليق، + استخدام فئة بناء أطباء الأسنان. -## unknown +## غير معروف `[other]` **وصف:** -This method returns the type and name of the code construct linked to a comment +ترجع هذه الطريقة نوع واسم بناء الرمز المرتبط بالتعليق -**Examples:** +**أمثلة:** -```javascript -const file = new SourceFile('file.ts'); +```جافا سكريبت +ملف جديد = SourceFile ('file.ts')؛ - const comment = new Comment({ - startLocation: { line: 1, column: 1 }, - endLocation: { line: 1, column: 1 }, - content: 'This is a comment' + التعليق = تعليق جديد ({ ) + موقع البداية: { line: 1, column: 1 }، + الموقع الطرفي: { line: 1, column: 1 }, + المحتوى: "هذا تعليق" }); - file.getLinkedCodeConstructInfo(comment); + file.getLinkedCodeConstructInfo(تعليق)؛ // => { type: 'class', name: 'StringUtil' } ``` From e3ce94944e73d9a484519db4d2bf243e5792a23c Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 14:26:36 +0100 Subject: [PATCH 37/61] New translations index.qmd (Arabic, Saudi Arabia) --- .../ar/docs/chapters/functional doc/utilities/index.qmd.ar.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/translations/ar/docs/chapters/functional doc/utilities/index.qmd.ar.qmd b/translations/ar/docs/chapters/functional doc/utilities/index.qmd.ar.qmd index 029c7d18..fa950f4e 100644 --- a/translations/ar/docs/chapters/functional doc/utilities/index.qmd.ar.qmd +++ b/translations/ar/docs/chapters/functional doc/utilities/index.qmd.ar.qmd @@ -1,3 +1,3 @@ --- -title: utilities +title: المنافع العامة --- From 210aaf9b19f2cd021e37a910d474ab16d0b7a054 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 14:26:37 +0100 Subject: [PATCH 38/61] New translations logger.qmd (Arabic, Saudi Arabia) --- .../ar/docs/chapters/functional doc/utilities/logger.qmd.ar.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/translations/ar/docs/chapters/functional doc/utilities/logger.qmd.ar.qmd b/translations/ar/docs/chapters/functional doc/utilities/logger.qmd.ar.qmd index 7eff27c6..aa20a564 100644 --- a/translations/ar/docs/chapters/functional doc/utilities/logger.qmd.ar.qmd +++ b/translations/ar/docs/chapters/functional doc/utilities/logger.qmd.ar.qmd @@ -1,5 +1,5 @@ # Logger -this module is used to log messages to the console +يتم استخدام هذه الوحدة لتسجيل الرسائل إلى وحدة التحكم From 10327837e77f340f09f9593f5b778ee1a66c887c Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 14:26:38 +0100 Subject: [PATCH 39/61] New translations parser.qmd (Arabic, Saudi Arabia) --- .../utilities/parser.qmd.ar.qmd | 100 +++++++++--------- 1 file changed, 50 insertions(+), 50 deletions(-) diff --git a/translations/ar/docs/chapters/functional doc/utilities/parser.qmd.ar.qmd b/translations/ar/docs/chapters/functional doc/utilities/parser.qmd.ar.qmd index 9a93cf27..40da9dd9 100644 --- a/translations/ar/docs/chapters/functional doc/utilities/parser.qmd.ar.qmd +++ b/translations/ar/docs/chapters/functional doc/utilities/parser.qmd.ar.qmd @@ -1,38 +1,38 @@ # Parser -this file is responsible for parsing comments in code files. - it extracts various pieces of information such as - description, category, subcategory, link, parameters, return values, - and thrown errors from comments using regular expressions. +هذا الملف مسؤول عن تحليل التعليقات في ملفات التعليمات البرمجية. + وهي تستخرج أجزاء مختلفة من المعلومات مثل + وصف الفئة، الفئة الفرعية، الرابط، المعلمات، قيم الإرجاع، + و ألقى أخطاء من التعليقات باستخدام التعبيرات العادية. -## descriptionMatch +## وصف المطابقة `[متغير]` **وصف:** -This method will extract the description from the comments block +هذه الطريقة سوف تستخرج الوصف من كتلة التعليقات -**Examples:** +**أمثلة:** -```javascript -Parser.getDescription(comment) => 'This method will extract the description from the comments block' +```جافا سكريبت +Parser.getDescription(تعليق) => "هذه الطريقة سوف تستخرج الوصف من كتلة التعليقات" ``` -## categoryMatches +## فئة المطابقات `[متغير]` **وصف:** -This method will extract the category from the comments block +هذه الطريقة سوف تستخرج الفئة من كتلة التعليقات -**Examples:** +**أمثلة:** -```javascript -Parser.getCategory(comment) => 'StringUtil' +```جافا سكريبت +Parser.getcategorory(تعليق) => 'StringUtil' ``` @@ -41,28 +41,28 @@ Parser.getCategory(comment) => 'StringUtil' `[متغير]` **وصف:** -This method will extract the subcategory from the comments block +هذه الطريقة سوف تستخرج الفئة الفرعية من كتلة التعليقات -**Examples:** +**أمثلة:** -```javascript -Parser.getSubCategory(comment) => 'StringUtil' +```جافا سكريبت +Parser.getSubcategorory(تعليق) => 'StringUtil' ``` -## linkRegex +## رابط Regex `[متغير]` **وصف:** -This method will extract the link from the comments block +هذه الطريقة سوف تستخرج الرابط من كتلة التعليقات -**Examples:** +**أمثلة:** -```javascript -Parser.getLink(comment) => 'StringUtil' +```جافا سكريبت +Parser.getLink(تعليق) => 'StringUtil' ``` @@ -71,13 +71,13 @@ Parser.getLink(comment) => 'StringUtil' `[متغير]` **وصف:** -This method will extract all the params from the comments block +هذه الطريقة سوف تستخرج كل البارام من كتلة التعليقات -**Examples:** +**أمثلة:** -```javascript -Parser.getParams(comment) => [{name: 'str', type: 'string', description: 'The string to convert to camel case'}] +```جافا سكريبت +Parser.getParams(تعليق) => [{name: 'str', type: 'string', description: 'The string to convert to camel case'}] ``` @@ -86,28 +86,28 @@ Parser.getParams(comment) => [{name: 'str', type: 'string', description: 'The st `[متغير]` **وصف:** -This method will extract the module name from the comments block +هذه الطريقة سوف تستخرج اسم الوحدة من كتلة التعليقات -**Examples:** +**أمثلة:** -```javascript -Parser.getModuleName(comment) => 'StringUtil' +```جافا سكريبت +Parser.getModuleName(تعليق) => 'StringUtil' ``` -## returnsMatches +## عمليات الإرجاع `[متغير]` **وصف:** -This method will extract the returns from the comments block +هذه الطريقة سوف تستخرج المردود من كتلة التعليقات -**Examples:** +**أمثلة:** -```javascript -Parser.getReturnsValues(comment) => [{type: 'string', description: 'The string to convert to camel case'}] +```جافا سكريبت +Parser.getReturnsValues(تعليق) => [{type: 'string', description: 'The string to convert to camel case'}] ``` @@ -116,42 +116,42 @@ Parser.getReturnsValues(comment) => [{type: 'string', description: 'The string t `[متغير]` **وصف:** -This method will extract the examples from the comments block +هذه الطريقة سوف تستخرج الأمثلة من كتلة التعليقات -**Examples:** +**أمثلة:** -```javascript -Parser.getExamples(comment) => ['StringUtil.convertToCamelCase(\'hello world\') => \'helloWorld\''] +```جافا سكريبت +Parser.getexamples(comy) => ['StringUtil.convertToCamelCase(\'hello world\') => \'helloWorld\'] ``` -## throwsMatches +## الرماة `[متغير]` **وصف:** -This method will extract the thrown errors from the comments block +هذه الطريقة سوف تستخرج الأخطاء الملقاة من كتلة التعليقات -**Examples:** +**أمثلة:** -```javascript -Parser.getThrownErrors(comment) => [{type: 'Error', description: 'The string to convert to camel case'}] +```جافا سكريبت +Parser.getThrownErrors(تعليق) => [{type: 'Error', description: 'The string to convert to camel case'}] ``` -## referencesRegex +## مراجع Regex `[متغير]` **وصف:** -This method will extract the references from the comments block +هذه الطريقة سوف تستخرج المراجع من كتلة التعليقات -**Examples:** +**أمثلة:** -```javascript -Parser.getReferences(comment) => [{text: 'StringUtil', type: 'localModule'}] +```جافا سكريبت +Parser.getReferences(تعليق) =[{text: 'StringUtil', type: 'localModule'}] ``` From c2fc796c557cb01cc1629a4b7caa39f5d2c5214a Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 14:26:39 +0100 Subject: [PATCH 40/61] New translations writer.qmd (Arabic, Saudi Arabia) --- .../utilities/writer.qmd.ar.qmd | 64 +++++++++---------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/translations/ar/docs/chapters/functional doc/utilities/writer.qmd.ar.qmd b/translations/ar/docs/chapters/functional doc/utilities/writer.qmd.ar.qmd index 77e5b654..4f860132 100644 --- a/translations/ar/docs/chapters/functional doc/utilities/writer.qmd.ar.qmd +++ b/translations/ar/docs/chapters/functional doc/utilities/writer.qmd.ar.qmd @@ -1,104 +1,104 @@ -# Writer +# كاتب -this typescript module (writer) contains classes and functions - for generating documentation structure and content. - it interacts with various files and directories to organize - documentation chapters, write content to markdown files, - and generate quarto yaml configuration for the documentation book. +هذه الوحدة النصية النصية (كاتب) تحتوي على فئات ووظائف + لتوليد هيكل الوثائق ومحتواها. + يتفاعل مع مختلف الملفات والدلائل لتنظيم + فصول التوثيق، وكتابة المحتوى إلى ملفات markdown، + و إنشاء إعداد quarto yaml لكتاب الوثائق. - note: this module is not yet complete and is still under development. + ملاحظة: هذه الوحدة لم تكتمل بعد ولا تزال قيد التطوير. -## _a +## _أ `[متغير]` -## unknown +## غير معروف `[other]` **وصف:** -Formats file names by removing all underscores `(_)` +تنسيق أسماء الملفات عن طريق إزالة جميع الشرطات السفلية `(_)` -## unknown +## غير معروف `[other]` **وصف:** -This method generates the Quarto YAML configuration file based on the provided chapters. +هذه الطريقة تولد ملف تكوين Quarto YAML استنادًا إلى الفصول المقدمة. -## _a +## _أ `[متغير]` **وصف:** -Creates modules and Categories from tutorials config, these will be required to write them as chapters in the quarto.yml file +إنشاء وحدات وتصنيفات من تكوين الدروس, هذه ستكون مطلوبة لكتابتها كفصول في ملف quarto.yml -## unknown +## غير معروف `[function]` **وصف:** -Copies the content of the tutorials in `/tutorials` to `/docs/chapters/tutorials` +نسخ محتوى الدروس في `/tutorials` إلى `/docs/chapters/tutorials` -## module +## وحدة `[متغير]` **وصف:** -This method writes the documentation content for a module to a specified file path. +تكتب هذه الطريقة محتوى التوثيق لوحدة إلى مسار ملف محدد. **Params:** -| Name | Description | + الاسم الوصف | --- | --- | -| options | An object containing the module and destination path. | -| options.destinationPath | The destination path where the documentation will be written. | + خيارات كائن يحتوي على الوحدة ومسار الوجهة. | + خيارات.destinationPath مسار الوجهة حيث سيتم كتابة الوثائق. | -## categories +## فئات `[متغير]` **وصف:** -This method prepares the directory structure for documentation by creating necessary folders and files. +وتعد هذه الطريقة هيكل الدليل للوثائق عن طريق إنشاء المجلدات والملفات اللازمة. -## categories +## فئات `[متغير]` **وصف:** -This method writes documentation for each category to a corresponding file within the documentation directory. +هذه الطريقة تكتب الوثائق لكل فئة في ملف مناظر داخل دليل الوثائق. -## unknown +## غير معروف `[function]` **وصف:** -This method reads through the tutorials folder and copies them to the destination `/docs` folder, it also - follows the structure of the tutorials set by the `config.json` in the tutorials folder if any +هذه الطريقة تقرأ من خلال مجلد الدروس وتنسخها إلى مجلد الوجهة '/docs` أيضًا + تتبع بنية الدروس التي تم تعيينها من قبل `config.json' في مجلد الدروس إن وجدت. -## unknown +## غير معروف `[function]` **وصف:** -This method adds the tutorials as chapters into the _quarto.yml file +هذه الطريقة تضيف الدروس كفصول في ملف _quarto.yml @@ -108,7 +108,7 @@ This method adds the tutorials as chapters into the _quarto.yml file `[متغير]` **وصف:** -This method adds the language specs to the _quarto.yml file +هذه الطريقة تضيف مواصفات اللغة إلى ملف _quarto.yml @@ -118,5 +118,5 @@ This method adds the language specs to the _quarto.yml file `[متغير]` **وصف:** -This method creates a copy of each qmd file in the docs folder for each language +هذه الطريقة تنشئ نسخة من كل ملف qmd في مجلد المستندات لكل لغة From f335a07dd21f8ff8c52aff402a97053719d12cff Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 14:26:40 +0100 Subject: [PATCH 41/61] New translations globals.qmd (Arabic, Saudi Arabia) --- .../docs/chapters/globals/globals.qmd.ar.qmd | 46 +++++++++---------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/translations/ar/docs/chapters/globals/globals.qmd.ar.qmd b/translations/ar/docs/chapters/globals/globals.qmd.ar.qmd index 0a3a6aa2..c539dc0f 100644 --- a/translations/ar/docs/chapters/globals/globals.qmd.ar.qmd +++ b/translations/ar/docs/chapters/globals/globals.qmd.ar.qmd @@ -1,6 +1,6 @@ # Globals -global constructs +الإنشاءات العالمية @@ -8,46 +8,46 @@ global constructs `[function]` **وصف:** -This function recursively traverses the specified directory and its subdirectories to find JavaScript files (.js). - It starts by checking each item in the directory. If the item is a directory, it recursively calls itself - to search for JavaScript files within that directory. If the item is a JavaScript file, it adds the file path - to an array of found JavaScript files. +هذه الوظيفة تتعقب بشكل متكرر الدليل المحدد ودلائله الفرعية للعثور على ملفات جافا سكريبت (.js). + يبدأ بالتحقق من كل عنصر في الدليل. إذا كان البند دليل ، فإنه يتكرر الاتصال بنفسه + للبحث عن ملفات جافا سكريبت داخل ذلك الدليل. إذا كان العنصر ملف جافا سكريبت ، فإنه يضيف مسار الملف + إلى مجموعة من ملفات جافا سكريبت التي تم العثور عليها. -## start +## بداية `[function]` **وصف:** -Starts the documentation generation process. +يبدأ عملية توليد الوثائق. - This function initiates the documentation generation process by performing the following steps: + وتبدأ هذه الوظيفة عملية توليد الوثائق عن طريق القيام بالخطوات التالية: - 1. It searches for JavaScript files in the specified directory and its subdirectories. - 2. It parses the comments from each JavaScript file using `CommentsUtil.getCommentsFromFile()`. - 3. It processes the comments to extract module information and updates the module and category data structures accordingly. - 4. If a default module is defined, it adds the module and its documentation to the appropriate category or the default category. - 5. It generates the documentation directory and files using the `Writer` utility. - 6. Finally, it logs a message indicating that the documentation generation process is complete. + 1. يبحث عن ملفات جافا سكريبت في الدليل المحدد والدلائل الفرعية الخاصة به. + 2. يقارن التعليقات من كل ملف من ملفات JavaScript باستخدام `CommentsUtil.getCommentsFromFile()`. + 3. وهو يجهز التعليقات لاستخراج المعلومات النموذجية ويستكمل هياكل بيانات الوحدة وفئاتها وفقا لذلك. + 4. إذا تم تعريف الوحدة الافتراضية، فإنها تضيف الوحدة ومستنداتها إلى الفئة المناسبة أو الفئة الافتراضية. + 5. يقوم بإنشاء دليل الوثائق والملفات باستخدام أداة "الكتاب". + 6. وأخيرا، يسجل التقرير رسالة تشير إلى أن عملية توليد الوثائق قد اكتملت. - This function serves as the entry point for generating documentation for JavaScript files. + تعمل هذه الوظيفة كنقطة دخول لتوليد الوثائق لملفات جافا سكريبت. -## unknown +## غير معروف `[other]` **وصف:** -This method will convert a string to camel toUpperCase +هذه الطريقة ستقوم بتحويل سلسلة إلى جمال toUpperCase -**Examples:** +**أمثلة:** -```javascript +```جافا سكريبت StringUtil.convertToCamelCase('hello world') => 'helloWorld' StringUtil.convertToCamelCase('hello-world') => 'helloWorld' StringUtil.convertToCamelCase('hello_world') => 'helloWorld' @@ -57,16 +57,16 @@ StringUtil.convertToCamelCase('hello world') => 'helloWorld' -## unknown +## غير معروف `[other]` **وصف:** -This method will convert a string to camel toUpperCase +هذه الطريقة ستقوم بتحويل سلسلة إلى جمال toUpperCase -**Examples:** +**أمثلة:** -```javascript +```جافا سكريبت StringUtil.convertToCamelCase('hello world') => 'helloWorld' StringUtil.convertToCamelCase('hello-world') => 'helloWorld' StringUtil.convertToCamelCase('hello_world') => 'helloWorld' From edcebc9816ba41b8917456934c12017fdb6f56f7 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 14:26:41 +0100 Subject: [PATCH 42/61] New translations index.qmd (Arabic, Saudi Arabia) --- translations/ar/docs/chapters/globals/index.qmd.ar.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/translations/ar/docs/chapters/globals/index.qmd.ar.qmd b/translations/ar/docs/chapters/globals/index.qmd.ar.qmd index 430eb7aa..4a3c8467 100644 --- a/translations/ar/docs/chapters/globals/index.qmd.ar.qmd +++ b/translations/ar/docs/chapters/globals/index.qmd.ar.qmd @@ -1,3 +1,3 @@ --- -title: Globals +العنوان: العالمية --- From a1c4fa20fdc3c1a1af0d04e7b444577d2808a307 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 14:26:42 +0100 Subject: [PATCH 43/61] New translations changelog.qmd (Arabic, Saudi Arabia) --- .../chapters/tutorials/changelog.qmd.ar.qmd | 56 +++++++++---------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/translations/ar/docs/chapters/tutorials/changelog.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/changelog.qmd.ar.qmd index 76d282a9..3c48caa1 100644 --- a/translations/ar/docs/chapters/tutorials/changelog.qmd.ar.qmd +++ b/translations/ar/docs/chapters/tutorials/changelog.qmd.ar.qmd @@ -1,43 +1,43 @@ -### Changelog +### التغييرات --- -title: Change log +title: سجل التغيير --- - -# Changelog + +# تغيير -All notable changes to this project will be documented in this file. +وسيتم توثيق جميع التغييرات الملحوظة في هذا المشروع في هذا الملف. -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +التنسيق مبني على [الحفاظ على تغيير](https://keepachangelog.com/en/1.0.0/) +ويلتزم هذا المشروع بـ [النسخة السامية](https://semver.org/spec/v2.0.0.html). -## Unreleased (2024-03-05) +## لم يفرج (2024-03-05) -### 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)) +- استخراج مستخرجات من ملفات جافا سكريبت ([`#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)) -### 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)) +### تم إصلاح الأخطاء: +- تحسين التنسيق لـ `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)) -#### Contributors ✨ +#### المساهمون ✨ -Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)): +شكرا لهؤلاء الناس الرائعين (مفتاح [emoji](https://allcontributors.org/docs/en/emoji-key)): - + - + @@ -46,14 +46,14 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
- + - + -This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! +هذا المشروع يتبع مواصفات [all-contributors](https://github.com/all-contributors/all-contributors). المساهمات من أي نوع! - + [cc-by]: http://creativecommons.org/licenses/by/4.0/ [cc-by-image]: https://i.creativecommons.org/l/by/4.0/88x31.png From cc616c6666953346261ded8b952e8607066a00a6 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 14:26:43 +0100 Subject: [PATCH 44/61] New translations improving_documentation.qmd (Arabic, Saudi Arabia) --- .../improving_documentation.qmd.ar.qmd | 214 +++++++++--------- 1 file changed, 107 insertions(+), 107 deletions(-) diff --git a/translations/ar/docs/chapters/tutorials/contributing/improving_documentation.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/contributing/improving_documentation.qmd.ar.qmd index f0571fef..0e9dd095 100644 --- a/translations/ar/docs/chapters/tutorials/contributing/improving_documentation.qmd.ar.qmd +++ b/translations/ar/docs/chapters/tutorials/contributing/improving_documentation.qmd.ar.qmd @@ -1,110 +1,110 @@ -###Improving-documentation +###تحسين التوثيق -## Improving Documentation with JSDoc +## تحسين التوثيق باستخدام JSDoc -### Introduction +### مقدمة -Effective documentation is crucial for maintaining a clear and understandable codebase. One powerful tool for enhancing documentation within your code is JSDoc. JSDoc is a markup language that allows you to annotate your code with structured comments, enabling automatic generation of documentation. In this guide, we will explore the uses of JSDoc and how it can improve your project's documentation. +فالتوثيق الفعال أمر بالغ الأهمية للمحافظة على علاقة مشتركة واضحة ومفهومة. إحدى الأدوات القوية لتعزيز التوثيق في الكود الخاص بك هي JSDoc. JSDoc هي لغة ترميز تسمح لك بالتعليق على التعليمات البرمجية الخاصة بك مع تعليقات منظمة، مما يتيح التوليد التلقائي للوثائق. في هذا الدليل، سوف نستكشف استخدامات JSDoc وكيف يمكن تحسين توثيق مشروعك. -### Using JSDoc for Genereated Documentation +### استخدام JSDoc للوثائق الوراثية -One of the primary uses of JSDoc is to generate documentation directly from your codebase. By adding JSDoc comments to your functions, classes, and variables, you can provide essential information that is automatically extracted and transformed into comprehensive documentation. +أحد الاستخدامات الأساسية لـ JSDoc هو توليد التوثيق مباشرة من الكود الخاص بك. من خلال إضافة تعليقات JSDoc إلى الدوال والصفوف والمتغيرات الخاصة بك، يمكنك توفير معلومات أساسية يتم استخراجها تلقائياً وتحويلها إلى وثائق شاملة. -To use JSDoc for generating documentation, follow these steps: +لاستخدام JSDoc لتوليد الوثائق، قم باتباع الخطوات التالية: -1. Markup Comments: Add JSDoc comments directly above the code elements you want to document. Use the /\*_ ... _/ syntax to indicate a JSDoc comment block. +1. تعليقات الترميز: أضف تعليقات JSDoc مباشرة فوق عناصر التعليمات البرمجية التي تريد توثيقها. استخدام /\*_ ... _/ بناء الجملة للإشارة إلى كتلة تعليقات JSDoc . -2. Documenting Functions: Use JSDoc tags to describe function parameters, return values, and additional information. Tags like @param, @returns, and @description are commonly used for this purpose. Other important custom tags are @category and @subcategory, these tags help to structure the generated documentation into chapters. All modules under a `subcategory` will be under one chapter, the chapter name will correspond to the name assigned to the `subcategory`. - The main idea around @category and @subcategory is to allow nested chapters for example one parent chapter A can have other subchapters (Chapter Aa, Chapter Ab, Chapter Ac) with each of these subchapters having their individual modules. - Note that this is only two levels of nesting, with Chapter A being the @category and the @subcategory will be the other chapters. Initially we intend to implement 2 levels of nested chapters but this as at the time of writing this quarto only allows 1 levels of nesting (i.e, you can only have 1 parent chapter with no subChapters, as a result, only the @subcategories will be displayed as chapters in the rendered document. +2. وظائف التوثيق: استخدام وسوم JSDoc لوصف معلمات الدالة، قيم الإرجاع، ومعلومات إضافية. العلامات مثل @param و @returns و @description شائعة الاستخدام لهذا الغرض. العلامات المخصصة المهمة الأخرى هي @category و @subcategory، هذه العلامات تساعد على هيكلة الوثائق التي تم إنشاؤها في فصول. وستكون جميع الوحدات تحت `فئة فرعية` تحت فصل واحد، وسيتطابق اسم الفصل مع الاسم المعين لـ `الفئة الفرعية`. + الفكرة الرئيسية حول الفئتين @category و @subcategory هي السماح للفصول المتداخلة على سبيل المثال يمكن أن يحتوي الفصل الأول ألف على فصول فرعية أخرى (الفصل ألف (أ). () الفصل أب - الفصل ألف) مع كل فصل من هذه الفصول الفرعية وحدات خاصة بها. + لاحظ أن هذا هو مستويين فقط من التعقيد، حيث أن الفصل ألف هو الفئة @والفئة الفرعية @@ ستكون هي الفصول الأخرى. نعتزم في البداية تنفيذ مستويين من الفصول المتداخلة، ولكن هذا في وقت كتابة هذا الربع لا يسمح إلا لمستوى واحد من التعبيد (١). ، يمكن أن يكون لديك فصل واحد فقط مع عدم وجود فصول فرعية، نتيجة لذلك، فقط الفئات الفرعية @سوف يتم عرضها كفصول في الوثيقة المقدمة. -3. Documenting Classes: For classes, use JSDoc comments to provide descriptions, document class properties, and document class methods. Tags like @class, @property, and @method are commonly used in this context. +3. فئات التوثيق: بالنسبة للصفوف الدراسية، استخدم تعليقات JSDoc لتوفير الأوصاف، وخصائص الصف المستندي، وطرائق فصل المستند. العلامات مثل @clas، @propers، و @method شائعة الاستخدام في هذا السياق. -4. Running JSDoc Generation: Use a JSDoc generator tool, such as JSDoc itself or other popular tools like TypeDoc or JSDoc3, to parse your codebase and generate the documentation output. Configure the generator to target the desired output format, such as HTML or Markdown. +4. تشغيل توليد JSDoc : استخدام أداة مولد JSDoc ، مثل JSDoc نفسه أو أدوات شعبية أخرى مثل TypeDoc أو JSDoc3, لتحليل الكود الخاص بك وإنشاء إخراج الوثائق. تكوين المولد لاستهداف تنسيق المخرج المطلوب، مثل HTML أو Markdown. -5. Review and Update: Review the generated documentation and ensure it accurately represents your code. Update the JSDoc comments as needed to provide clearer explanations or additional information. +5. مراجعة وتحديث: مراجعة الوثائق التي تم إنشاؤها والتأكد من أنها تمثل الرمز الخاص بك بدقة. تحديث تعليقات JSDoc حسب الحاجة لتقديم تفسيرات أو معلومات إضافية أوضح. -For more information on using JSDoc for generating documentation, see the [JSDoc documentation](https://jsdoc.app/) or [Getting started with JSDoc](https://jsdoc.app/about-getting-started.html). +لمزيد من المعلومات حول استخدام JSDoc لتوليد الوثائق، انظر [وثائق JSDoc ](https://jsdoc.app/) أو [Getting بدأ باستخدام JSDoc](https://jsdoc.app/about-getting-started.html). -### Using JSDoc for Writing Documentation +### استخدام JSDoc لكتابة الوثائق -JSDoc can also be used beyond generating code documentation. Its flexible syntax and tagging system make it a valuable tool for writing other aspects of your project's documentation, such as tutorials, guides, and reference materials. +كما يمكن استخدام JSDoc بما يتجاوز إصدار الوثائق الرمزية نظام بناء الجملة والعلامة المرن لديه يجعله أداة قيمة لكتابة جوانب أخرى من وثائق مشروعك، مثل الدروس والأدلة والمواد المرجعية. -To use JSDoc for writing documentation, consider the following approaches: +لاستخدام JSDoc لكتابة الوثائق، يرجى النظر في النُهج التالية: -1. Tutorials and Guides: Utilize JSDoc comments to write step-by-step tutorials and guides within your codebase. By embedding tutorial content in JSDoc comments, you can keep the documentation closely tied to the relevant code, making it easier for developers to follow along and understand the concepts. +1. الدروس والإرشاد: استخدام تعليقات JSDoc لكتابة دروس ودلائل خطوة بخطوة داخل الكود الخاص بك. عن طريق تضمين المحتوى التعليمي في تعليقات JSDoc ، يمكنك الحفاظ على ارتباط الوثائق بشكل وثيق مع الكود ذي الصلة، يجعل من الأسهل على المطورين متابعة المفاهيم وفهمها. -2. Inline Examples: Use JSDoc comments to include inline code examples that demonstrate the usage of functions, classes, or modules. These examples can serve as both instructional material and a quick reference for developers. +2. أمثلة مضمنة: استخدم تعليقات JSDoc لتضمينها أمثلة على الرموز المضمنة التي توضح استخدام الدوال أو الصفوف أو الوحدات. ويمكن استخدام هذه الأمثلة كمادة تعليمية وكمرجع سريع للمطورين. -3. Reference Materials: JSDoc comments can be used to provide additional information in reference materials, such as explaining design patterns, outlining best practices, or clarifying complex concepts. Leverage JSDoc tags like @example or @see to link to relevant resources or code examples. +3. المواد المرجعية: يمكن استخدام تعليقات JSDoc لتوفير معلومات إضافية في المواد المرجعية. مثل شرح أنماط التصميم، أو تحديد أفضل الممارسات، أو توضيح المفاهيم المعقدة. وسوم Leverage JSDoc مثل @example أو @see لربط الموارد أو أمثلة التعليمات البرمجية ذات الصلة. -4. Integration with Markdown: JSDoc supports Markdown within comments, allowing you to incorporate formatted text, headings, lists, and other Markdown features into your documentation. This enables you to create more visually appealing and structured content within your JSDoc comments. +4. التكامل مع Markdown: JSDoc يدعم Markdown ضمن التعليقات، مما يسمح لك بدمج النصوص المنسقة والعناوين والقوائم وغيرها من ميزات Markdown في وثائقك. هذا يمكّنك من إنشاء محتوى أكثر جاذبية بصرياً وتنظيماً في تعليقات JSDoc الخاصة بك. -### Improving JSQuarto documentation with JSDoc +### تحسين وثائق JSQuarto باستخدام JSDoc -The JSQuarto documentation is not yet complete. There are several areas that could be improved, including: +ولم تكتمل بعد وثائق JSQuarto. وهناك عدة مجالات يمكن تحسينها، بما في ذلك: -- More detailed explanations of the JSQuarto project structure and codebase -- Additional information on how to contribute to the project -- Implementing JSQuarto as a CLI tool -- Additional information on how to maintain the JSQuarto project -- Additional information on how to deploy the JSQuarto project -- Project roadmap and future plans +- إيضاحات أكثر تفصيلا لهيكل مشروع JSQuarto ومشروع الشفرة +- معلومات إضافية عن كيفية المساهمة في المشروع +- تنفيذ JSQuarto كأداة للمبادرة القطرية +- معلومات إضافية عن كيفية الحفاظ على مشروع JSQuarto +- معلومات إضافية عن كيفية نشر مشروع JSQuarto +- خريطة الطريق للمشروع والخطط المستقبلية -To improve the JSQuarto documentation, you can use JSDoc to add additional documentation directly within the codebase. This will allow you to provide more detailed explanations of the code and project structure, as well as additional information on how to contribute to the project, how to use the JSQuarto API, and how to maintain and deploy the project. As at the time of writing this, the documentation was built with other packages to improve the User interface, one of which is [Better-docs](https://github.com/SoftwareBrothers/better-docs). +لتحسين وثائق JSQuarto ، يمكنك استخدام JSDoc لإضافة وثائق إضافية مباشرة داخل المركز البرمجي. هذا سيمكنك من تقديم إيضاحات أكثر تفصيلا للشفرة وهيكل المشروع، بالإضافة إلى معلومات إضافية عن كيفية المساهمة في المشروع، كيفية استخدام واجهة برمجة تطبيقات JSQuarto ، وكيفية صيانة المشروع ونشره. في وقت كتابة هذا، تم بناء الوثائق مع حزم أخرى لتحسين واجهة المستخدم، أحدها [Better-docs](https://github.com/SoftwareBrothers/better-docs). -### Tutorials guide +### دليل الدروس -This section provides an overview of the `config.json` files used in the JSQuarto documentation, specifically focusing on the `tutorials` folder. The `config.json` file serve as configuration files that help structure and organize the documentation, while the `tutorials` folder contains the Markdown files for various tutorials. +يقدم هذا القسم لمحة عامة عن ملفات `config.json` المستخدمة في وثائق JSQuarto، مع التركيز تحديداً على مجلد `tutorials`. ملف `config.json' يعمل كملفات تكوين تساعد على هيكلة وتنظيم الوثائق، في حين أن مجلد `الدروس` يحتوي على ملفات Markdown لمختلف الدروس. -#### The `tutorials` Folder +#### مجلد `الدروس التعليمية` -The `tutorials` folder within the documentation directory is dedicated to hosting tutorials on various topics related to the JSQuarto platform. This folder contains a collection of Markdown files, each representing an individual tutorial. +مجلد "الدروس" داخل دليل التوثيق مكرس لاستضافة دروس حول مختلف المواضيع ذات الصلة بمنصة JSQuarto. يحتوي هذا المجلد على مجموعة من ملفات Markdown، يمثل كل منها درسا فرديا. -Markdown is a lightweight markup language that allows for easy formatting and structuring of text, making it ideal for creating tutorials. Markdown files provide a simple yet powerful way to document step-by-step instructions, code examples, explanations, and other relevant information. +Markdown هي لغة علامة خفيفة الوزن تسمح بسهولة تنسيق وبنية النص، مما يجعلها مثالية لإنشاء دروس. توفر ملفات Markdown طريقة بسيطة ولكنها قوية لتوثيق التعليمات خطوة بخطوة، والأمثلة البرمجية، والتفسيرات وغيرها من المعلومات ذات الصلة. -The `tutorials` folder can be organized into subfolders to further categorize and group related tutorials. This helps users easily locate and access the tutorials they need based on their specific interests or requirements. +يمكن تنظيم مجلد "الدروس" في مجلدات فرعية لزيادة تصنيف ودروس ذات صلة بالمجموعة. وهذا يساعد المستخدمين على تحديد مواقع الدروس التي يحتاجونها بسهولة والوصول إليها بناء على اهتماماتهم أو متطلباتهم المحددة. -By structuring tutorials within the `tutorials` folder using Markdown, contributors can contribute new tutorials, update existing ones, and ensure that the documentation remains comprehensive and user-friendly. +من خلال هيكلة الدروس داخل مجلد "الدروس" باستخدام Markdown، يمكن للمساهمين المساهمة بدروس جديدة، تحديث الوثائق الموجودة، وضمان أن تظل الوثائق شاملة وسهلة الاستعمال. -Overall, the combination of `.json` files and the `tutorials` folder enables a well-organized and accessible documentation structure, allowing users to navigate and explore the JSQuarto platform documentation with ease. +وعموما، فإن الجمع بين `. ملفات son` ومجلد "الدروس التعليمية" يمكنان من بنية وثائق منظمة تنظيماً جيداً ويمكن الوصول إليها، مما يسمح للمستخدمين بالتنقل واستكشاف وثائق منصة JSQuarto بسهولة. -#### Overview of `config.json` Files +#### نظرة عامة على ملفات `config.json` -The `config.json` file in the JSQuarto documentation play a crucial role in organizing and categorizing the content. This file define the structure of the documentation and provide metadata for each section, tutorial, or topic. They allow maintainers and contributors to easily navigate and manage the documentation by specifying titles, creating nested structures, and linking related topics. +يؤدي ملف `config.json' في وثائق JSQuarto دورا حاسما في تنظيم وتصنيف المحتوى. يحدد هذا الملف هيكل الوثائق ويوفر بيانات فوقية لكل قسم أو برنامج تعليمي أو موضوع. فهي تسمح للقائمين على الصيانة والمساهمين بالتنقل في الوثائق وإدارتها بسهولة عن طريق تحديد العناوين وإنشاء هياكل متداخلة وربط المواضيع ذات الصلة. -By using `config.json` file, the documentation can be dynamically generated and updated based on the defined structure. This makes it easier to maintain consistency, track changes, and add new content. +باستخدام ملف `config.json' ، يمكن إنشاء الوثائق وتحديثها ديناميكيا استنادا إلى الهيكل المحدد. وهذا يجعل من الأسهل الحفاظ على الاتساق، وتتبع التغييرات، وإضافة محتوى جديد. -#### The `.json` configuration -Let's explain how this structure works by looking at the `config.json` file in the `tutorials /` folder. This file defines the structure of the tutorials section of the documentation, including the titles, descriptions links for each tutorial. +#### تكوين `.json` +لنشرح كيف تعمل هذه البنية من خلال النظر إلى ملف `config.json` في مجلد `tutorials /`. يحدد هذا الملف هيكل قسم الدروس في الوثائق، بما في ذلك العناوين، وصلات الوصف لكل دورة تعليمية. ```json { - "changelog": { - "title": "Changelog" + "سجل التغييرات": { + "العنوان: "التغيير" }, "environment_setup": { - "title": "Environment Setup" + "العنوان": "إعداد البيئة" }, - "contributing": { - "title": "Contributing" + "المساهمة": { + "العنوان": "المساهمة" } } ``` -In this example, the `.json` file defines the titles and relationships of the main sections within your documentation. The sections are represented as objects, with each object having a unique key and a `"title"` key-value pair. -1. "changelog" represents the "Changelog" section. The `"title"` key-value pair specifies the title of this section as "Changelog." +في هذا المثال ، يحدد ملف 'json' عناوين وعلاقات الأقسام الرئيسية في وثائقك. الأقسام ممثلة ككائنات، مع كل كائن له مفتاح فريد و 'title"` زوج قيم مفتاح. +1. "سجل التغييرات" يمثل قسم "التغييرات". يحدد زوج القيمة الرئيسية "title" عنوان هذا القسم بأنه "التغيير". -2. "environment_setup" represents the "Environment Setup" section. The `"title"` key-value pair specifies the title of this section as "Environment Setup." +2. "Environ_setup" يمثل قسم "إعداد البيئة". يحدد زوج القيمة الرئيسية "title" عنوان هذا القسم بأنه "إعداد البيئة". -3. "contributing" represents the "Contributing" section. The `"title"` key-value pair specifies the title of this section as "Contributing." +3. يمثل "المساهمة" قسم "المساهمة". يحدد زوج القيمة الرئيسية "title" عنوان هذا القسم بأنه "المساهمة". -With this structure, your documentation folder will contain separate Markdown files for each section, named according to the keys in the `.json` file. For example: +مع هذا الهيكل، سيتضمن مجلد الوثائق الخاص بك ملفات ماركداون منفصلة لكل قسم، اسمها وفقا للمفاتيح في ملف `.json'. وعلى سبيل المثال: -```yaml -- `documentation /` +“يامل +- `الوثائق/` - `docs /` - `changelog.md` - `environment_setup.md` @@ -112,89 +112,89 @@ With this structure, your documentation folder will contain separate Markdown fi - `tutorials.json` ``` -Each Markdown file will correspond to a section in your documentation and should contain the relevant content for that section. +كل ملف Markdown سوف يتطابق مع قسم في وثائقك ويجب أن يحتوي على المحتوى ذي الصلة لذلك القسم. -This simplified structure allows you to organize your documentation into distinct sections, making it easier for readers to locate and access the specific topics they need. It provides a clear and concise way to represent the main sections of your documentation without the need for nested tutorials or complex hierarchies. +هذا الهيكل المبسط يسمح لك بتنظيم وثائقك في أقسام متميزة، يجعل من الأسهل على القراء تحديد المواقع والوصول إلى المواضيع المحددة التي يحتاجون إليها. يوفر طريقة واضحة وموجزة لتمثيل الأقسام الرئيسية من وثائقك دون الحاجة إلى دروس متداخلة أو تسلسل هرمي معقد. -Remember to update the `.json` file whenever you add or modify sections to ensure that the documentation structure accurately reflects the content of your documentation. +تذكر أن تقوم بتحديث ملف '.json' كلما قمت بإضافة أو تعديل الأقسام للتأكد من أن هيكل التوثيق يعكس بدقة محتوى وثائقك. -By following this structure, you can maintain a well-organized and easily navigable documentation repository. +باتباع هذا الهيكل، يمكنك الحفاظ على مستودع وثائق جيد التنظيم وسهل التصفح. -#### Nested `.json` configuration for tutorials -To structure tutorials and create nested tutorials within your documentation, you can use the `.json` file to define the hierarchy and relationships between tutorials. Here's an example of how you can structure tutorials using a `.json` file: +#### إعدادات `.json` المتداخلة للدورات التعليمية +لهيكلة الدروس وإنشاء دروس متداخلة داخل وثائقك، يمكنك استخدام ملف '.json' لتحديد التسلسل الهرمي والعلاقات بين الدروس. إليك مثال على كيفية هيكلة الدروس باستخدام ملف `.json`: -```yaml +“يامل { - "maintainers": { - "title": "Technical guide for Maintainers", - "children": { + "المشرفين": { + "العنوان": "دليل تقني للقائمين"، + "الأطفال": { "reviewing_pr": { - "title": "Reviewing pull requests" + "title": "استعراض طلبات السحب" }, "ci_workflow": { - "title": "CI Workflow" + "title": "CI Workflow " }, - "secrets_and_security": { - "title": "Secret Access/Management" + "الأسرار_and_security": { + العنوان : "الوصول السري/الإدارة السرية" }, - "deployment_guide": { - "title": "Deployment Guide" + "نشر الدليل": { + "عنوان": "دليل النشر" } } }, - "contributing": { - "title": "Contributing to the project", - "children": { + "المساهمة": { + "title": "المساهمة في المشروع"، + "الأطفال": { "adding_a_course": { - "title": "Adding a course" + "title": "إضافة دورة" }, "api_project_structure": { - "title": "API project structure" + "title": "بنية مشروع API }, - "improving_documentation": { - "title": "Improving documentation" + "Improving_documentation": { + العنوان : "تحسين التوثيق" }, "project_structure": { - "title": "Project structure" + "عنوان": "بنية المشروع" }, "raising_issues": { - "title": "Raising issues" + العنوان: "إثارة المشاكل" }, "raising_pr": { - "title": "Raising pull requests" + "عنوان": "رفع طلبات الجذب" } } }, - "review": { - "title": "Reviewing the project" + "عرض": { + "title": "استعراض المشروع" } } ``` -In this example, the `.json` file represents a documentation structure with two main sections: "Technical guide for Maintainers" and "Technical guide for API developers". Each section has its own set of tutorials represented as nested objects. +وفي هذا المثال، يمثل ملف `json` هيكلا للتوثيق يتألف من قسمين رئيسيين: "الدليل التقني للمتعينين" و"الدليل التقني لمطوري API". لكل قسم مجموعته الخاصة من الدروس التي تمثل ككائنات متداخلة. -1. Define the main sections or categories as top-level objects within the `.json` file, such as "maintainers" and "contributing". +1. تعريف الأقسام أو الفئات الرئيسية على أنها الكائنات ذات المستوى الأعلى داخل ملف `json'، مثل "المشرفين" و "المساهمة". -2. Within each main section, provide a `"title"` key to specify the title or heading for that section. For example, "Technical guide for Maintainers" and "Technical guide for API developers". +2. ضمن كل قسم رئيسي، قدم مفتاح "عنوان" لتحديد عنوان أو عنوان ذلك القسم. () على سبيل المثال، "الدليل التقني للقائمين" و"الدليل التقني لمطوري API". -3. Add a `"children"` key within each main section to define the nested tutorials. Each tutorial is represented as a child object within the `"children"` object. Not all tutorials may have children tutorials, an example of this is the `review` tutorial. Since it has no children the program will only look for a `review.qmd` file and not a `review` folder +3. إضافة مفتاح 'الأطفال' داخل كل قسم رئيسي لتحديد الدروس المتداخلة. يتم تمثيل كل برنامج تعليمي ككائن ثانوي داخل كائن `الأطفال`. وقد لا تحتوي جميع الدروس على دروس للأطفال، ومن الأمثلة على ذلك دروس "مراجعة". بما أنه ليس لديه أطفال فإن البرنامج سيبحث فقط عن ملف "review.qmd" وليس مجلد "عرض" -4. For each tutorial, provide a unique key as the object's key, such as "reviewing_pr" and "ci_workflow". +4. لكل برنامج تعليمي، قم بتوفير مفتاح فريد كمفتاح الكائن، مثل "reviewing_pr" و "ci_workflow". -5. Within each tutorial object, include a `"title"` key to specify the title or heading for that specific tutorial. +5. ضمن كل كائن تعليمي، قم بإدراج مفتاح "title" لتحديد العنوان أو العنوان لذلك البرنامج التعليمي المحدد. -For this example here is what the folder structure would look like assuming the root folder is `tutorials /`: +على هذا المثال هنا ما سيبدو عليه هيكل المجلد بافتراض أن المجلد الجذري هو `دروس/`: -```yaml - - tutorials/ - - maintainers/ - - maintainers.qmd - - reviewing_pr.qmd +“يامل + - دروس/دروس + - المشرفون/ + - المشرفون + - الاستعراض_pr.qmd - ci_workflow.qmd - - secrets_and_security.qmd - - deployment_guide.qmd + - الأسرار_and_security.qmd + - نشر_guide.qmd - - contributing/ + - المساهمة/ - api.md - api_structure.md - api_authentication_flow.qmd @@ -206,15 +206,15 @@ For this example here is what the folder structure would look like assuming the - config.json ``` -In this structure: +وفي هذا الهيكل: -- The `.json` configuration file is located in the `tutorials/` folder -- The `tutorials` folder contains subfolders representing different sections or categories of tutorials. -- Each section or category folder, such as `maintainers` and `contributing`, contains the `.qmd` files for individual tutorials. - +- ملف التكوين 'json' موجود في المجلد 'دروس التعليمية' +- يحتوي مجلد "الدروس" على مجلدات فرعية تمثل أقسام أو فئات مختلفة من الدروس. +- كل قسم أو مجلد فئة، مثل 'المشرفين` و 'المساهمة`، يحتوي على ملفات '.qmd' لدروس فردية. + -The nested structure allows you to organize tutorials hierarchically, making it easier to navigate and find specific tutorials based on their topic or category. +الهيكل المتداخل يسمح لك بتنظيم الدروس هرمياً ، مما يجعل من الأسهل التنقل والبحث عن دروس محددة استناداً إلى موضوعها أو فئتها. -It's important to note that the tutorial structure allows only one level of nesting. This means you can have main sections and their respective tutorials, but you cannot create further nested folders within the tutorials. +من المهم ملاحظة أن بنية البرنامج التعليمي لا تسمح إلا بمستوى واحد من التعش. هذا يعني أنه يمكنك الحصول على الأقسام الرئيسية ودروسها، ولكن لا يمكنك إنشاء المزيد من المجلدات المتداخلة داخل الدروس. -By following this folder structure and accompanying `.qmd` overview files, you can easily define the hierarchy and relationships between tutorials, allowing you to create nested tutorials and organize your documentation in a logical and structured manner. +من خلال اتباع هيكل المجلدات هذا وما يرافقه `. md` ملفات نظرة عامة، يمكنك بسهولة تحديد التسلسل الهرمي والعلاقات بين الدروس، السماح لك بإنشاء دروس متداخلة وتنظيم وثائقك بطريقة منطقية ومنظمة. From 2963c749bc633733bd6ab9996e67b1377bc280ef Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 14:26:44 +0100 Subject: [PATCH 45/61] New translations raising_issues.qmd (Arabic, Saudi Arabia) --- .../contributing/raising_issues.qmd.ar.qmd | 56 +++++++++---------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/translations/ar/docs/chapters/tutorials/contributing/raising_issues.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/contributing/raising_issues.qmd.ar.qmd index f22b94f5..312dbbb8 100644 --- a/translations/ar/docs/chapters/tutorials/contributing/raising_issues.qmd.ar.qmd +++ b/translations/ar/docs/chapters/tutorials/contributing/raising_issues.qmd.ar.qmd @@ -1,45 +1,45 @@ -###Raising-issues +###رفع المشكلات -Raising issues is an essential part of contributing to an open source project. Before you start, it's recommended that you have a basic understanding of Markdown and GitHub, which are commonly used in this workflow. Markdown is a lightweight markup language that is used to format and style text on the web. You can find a comprehensive guide to [Markdown](https://guides.github.com/features/mastering-markdown/) on the GitHub website +وإثارة المسائل جزء أساسي من المساهمة في مشروع مفتوح المصدر. قبل البدء، من المستحسن أن يكون لديك فهم أساسي لـ Markdown و GitHub، اللذين يشيع استخدامهما في تدفق العمل هذا. Markdown هي لغة علامة خفيفة الوزن تستخدم لتنسيق النص وأسلوبه على الويب. يمكنك العثور على دليل شامل ل [Markdown](https://guides.github.com/features/mastering-markdown/) على موقع GitHub -If you're not familiar with GitHub, it's a web-based platform that provides tools for version control, code management, and collaboration. GitHub provides a step-by-step guide to getting started with their platform on their [website](https://guides.github.com/activities/hello-world/) +إذا كنت غير مألوف مع GitHub، فهي منصة على الإنترنت توفر أدوات للتحكم في الإصدار، وإدارة التعليمات البرمجية، والتعاون. GitHub يوفر دليل خطوة خطوة للبدء مع منصتهم على [website](https://guides.github.com/activities/hello-world/) -It's important to check whether your idea or issue has already been raised by someone else. You can do this by searching through the project's existing issues on GitHub. If you find an issue that is similar to yours, please comment on it to let others know that you're also interested in working on it. +من المهم التحقق مما إذا كانت فكرتك أو مشكلتك قد أثيرت بالفعل من قبل شخص آخر. يمكنك القيام بذلك عن طريق البحث من خلال المشكلات الموجودة في المشروع على GitHub. إذا وجدت مشكلة مشابهة لمشكلتك، يرجى التعليق عليها لإعلام الآخرين بأنك أيضا مهتم بالعمل عليها. -If the issue has already been closed, or if it only partially solves your problem, it's recommended that you open a new issue with a reference to the old one. This can help to keep the discussion organized and ensure that all relevant information is easily accessible. +إذا كانت المشكلة قد أغلقت بالفعل، أو إذا كانت تحل مشكلتك جزئيا فقط، من المستحسن أن تفتح مشكلة جديدة مع الإشارة إلى المشكلة القديمة. ومن شأن ذلك أن يساعد على إبقاء المناقشة منظمة وأن يكفل سهولة الوصول إلى جميع المعلومات ذات الصلة. -Remember, raising an issue is an opportunity to improve the project and contribute to the open source community. With a little bit of effort and attention to detail, you can help make a real difference +ويُذكر أن إثارة مسألة ما هي فرصة لتحسين المشروع والإسهام في مجتمع المصادر المفتوحة. مع القليل من الجهد والاهتمام للتفاصيل، يمكنك المساعدة في إحداث فرق حقيقي -### Issue templates -We have issue templates for different types of issues. Please use the appropriate template for your issue. If you're not sure which template to use, please use the `General` template. +### قالب المشكلة +لدينا نماذج لأنواع مختلفة من المشاكل. الرجاء استخدام القالب المناسب للمشكلة الخاصة بك. إذا كنت لست متأكدا من أي قالب يمكن استخدامه، فيرجى استخدام قالب "جنرال". -- General template ([preview](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/blob/main/.github/ISSUE_TEMPLATE/ISSUE_TEMPLATE.md)) : This is the default template for raising an issue. Use this template if you're not sure which template to use. -- Bug report template ([preview](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/blob/.github/ISSUE_TEMPLATE/bug_report.md)) : Use this template to report a bug or problem with the project. -- New feature Request template ([preview](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/blob/.github/ISSUE_TEMPLATE/new_course.md)) : Use this template to request permission to add a new course to the list. +- قالب عام ([preview](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/blob/main/.github/ISSUE_TEMPLATE/ISSUE_TEMPLATE.md)) : هذا هو النموذج الافتراضي لإثارة المشكلة. استخدم هذا القالب إذا كنت لست متأكدا من أي قالب يمكن استخدامه. +- قالب تقرير الأخطاء ([preview](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/blob/.github/ISSUE_TEMPLATE/bug_report.md)) : استخدم هذا القالب للإبلاغ عن خلل أو مشكلة مع المشروع. +- قالب طلب ميزة جديدة ([preview](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/blob/.github/ISSUE_TEMPLATE/new_course.md)) : استخدم هذا القالب لطلب إذن لإضافة دورة جديدة إلى القائمة. -### Writing a clear title and description -When opening an issue, it's important to write a clear and concise title that accurately reflects the problem or suggestion you want to raise. The title should be descriptive enough so that others can quickly understand the issue, but not too long or complicated. +### كتابة عنوان ووصف واضح +عند فتح مشكلة ما، من المهم كتابة عنوان واضح وموجز يعكس بدقة المشكلة أو الاقتراح الذي تريد إثارته. وينبغي أن يكون العنوان وصفيا بما فيه الكفاية لكي يتمكن الآخرون من فهم المسألة بسرعة، ولكن ليس طويلا أو معقدا. -In the issue description, provide as much detail as possible about the issue or suggestion. Include steps to reproduce the problem if applicable, and any relevant information or context that can help others understand the issue better. +وفي وصف القضايا، قدم أكبر قدر ممكن من التفاصيل بشأن المسألة أو الاقتراح. قم بإدراج خطوات لتكرار المشكلة إذا كان ذلك منطبقاً، وأي معلومات ذات صلة أو سياق يمكن أن يساعد الآخرين على فهم المسألة بشكل أفضل. -### Using Issue labels -Issue labels are used to categorize and organize issues in an open source project. They can help contributors quickly identify the type and status of an issue, and can also help maintainers prioritize and manage the project's backlog of issues. +### استخدام تسميات المشكلة +يتم استخدام تسميات الإصدار لتصنيف وتنظيم المشكلات في مشروع مفتوح المصدر. ويمكن أن تساعد المساهمين على تحديد نوع المشكلة ومركزها بسرعة. ويمكن أيضا أن يساعد المشرفين على تحديد أولويات القضايا المتراكمة في المشروع وإدارتها. -When raising an issue, make sure to choose the appropriate label(s) that best describes the issue. For example, if you're reporting a bug, you might use the "bug" label. If you're suggesting a new feature or improvement, you might use the "enhancement" label. +عند إثارة مشكلة، تأكد من اختيار التسمية المناسبة التي تصف المشكلة على أفضل وجه. على سبيل المثال، إذا كنت تبلغ عن خطأ، قد تستخدم علامة "الخطأ". إذا كنت تقترح ميزة جديدة أو تحسين، قد تستخدم تسمية "التحسينات". -Some common issue labels you might see in a GitHub project include: +بعض تسميات المشكلات الشائعة التي قد تراها في مشروع GitHub تشمل: -* Bug: Used to report an error or problem with the code or functionality of the project. -* Enhancement: Used to suggest a new feature or improvement to the project. -* Documentation: Used to suggest changes or improvements to the project's documentation. -* Help wanted: Used to indicate that the project maintainers are actively seeking contributions to help resolve the issue. -* Good first issue: Used to indicate that the issue is suitable for new contributors who are just getting started with the project. +* خطأ: تستخدم للإبلاغ عن خطأ أو مشكلة في كود المشروع أو وظيفته. +* تحسين: يستخدم لاقتراح سمة جديدة أو تحسين للمشروع. +* الوثائق: تستخدم لاقتراح تغييرات أو تحسينات في وثائق المشروع. +* المساعدة المطلوبة: استخدمت للإشارة إلى أن القائمين على المشروع يسعون بنشاط إلى الحصول على مساهمات للمساعدة في حل هذه المسألة. +* المشكلة الأولى جيدة: تستخدم للإشارة إلى أن المشكلة مناسبة للمساهمين الجدد الذين بدأوا للتو بالمشروع. -### Contributing to issue discussions -If you're interested in working on an issue, please leave a comment to let others know. This will help to avoid duplicate work and ensure that the issue is assigned to the right person. -Once you've opened an issue or commented on an existing one, it's important to actively participate in the discussion. This means responding to comments and questions from others, providing additional information or clarification if needed, and being open to feedback and suggestions. +### المساهمة في إصدار المناقشات +إذا كنت مهتما بالعمل على حل مشكلة، يرجى ترك تعليق لإبلاغ الآخرين. وسيساعد ذلك على تفادي الازدواجية في العمل وكفالة إسناد المسألة إلى الشخص المناسب. +بمجرد أن تفتحوا قضية أو تعلقوا على قضية قائمة، من المهم المشاركة بنشاط في المناقشة. وهذا يعني الرد على التعليقات والأسئلة الواردة من جهات أخرى، وتوفير معلومات أو إيضاحات إضافية عند الاقتضاء، والانفتاح على التعليقات والاقتراحات. -### Conclusion -Raising issues is an important part of contributing to open source projects. By following these guidelines, you can help ensure that your issue is clear, well-documented, and easy for others to understand. Remember to actively participate in discussions, follow up on issues, and contribute code if you're able to. With a little effort and collaboration, we can all help make open source projects better for everyone. +### استنتاج +وتشكل إثارة المسائل جزءا هاما من المساهمة في مشاريع المصادر المفتوحة. ومن خلال اتباع هذه المبادئ التوجيهية، يمكنكم المساعدة على ضمان أن تكون قضيتكم واضحة وموثقة توثيقاً جيداً وسهلة الفهم بالنسبة للآخرين. تذكر أن تشارك بنشاط في المناقشات، ومتابعة المشكلات، والمساهمة في التعليمات البرمجية إذا كنت قادرا على ذلك. مع القليل من الجهد والتعاون، يمكننا جميعا أن نساعد على جعل مشاريع المصدر المفتوح أفضل للجميع. From df7661ca1660dd7e211a7c354d62576f248eaca7 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 14:26:45 +0100 Subject: [PATCH 46/61] New translations raising_pr.qmd (Arabic, Saudi Arabia) --- .../contributing/raising_pr.qmd.ar.qmd | 62 +++++++++---------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/translations/ar/docs/chapters/tutorials/contributing/raising_pr.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/contributing/raising_pr.qmd.ar.qmd index 113548bf..f0b93ec1 100644 --- a/translations/ar/docs/chapters/tutorials/contributing/raising_pr.qmd.ar.qmd +++ b/translations/ar/docs/chapters/tutorials/contributing/raising_pr.qmd.ar.qmd @@ -1,52 +1,52 @@ ###Raising-pr -## Introduction -A pull request is a way for contributors to submit changes to a project maintained by others. The changes are proposed and then reviewed and potentially merged by the project maintainers. In this guide, we will walk you through the steps of making a pull request to the Open-Science-Community-Saudi-Arabia/JSquarto repository on GitHub. +## مقدمة +طلب السحب هو طريقة للمساهمين لإرسال تغييرات إلى مشروع يديره الآخرون. ويُقترح إجراء التغييرات ثم يقوم المشرفون على المشروع باستعراضها وربما دمجها. في هذا الدليل، سنمضي معكم عبر خطوات تقديم طلب سحب إلى مستودع العلوم المفتوحة - المجتمع السعودي - العربي/JSquarto في GitHub. -## Steps -1. Find a feature or bug that you want to work on. -2. Fork the Open-Science-Community-Saudi-Arabia/JSquarto repository to your GitHub account. -3. Clone the forked repository on your local machine. +## خطوات +1. ابحث عن ميزة أو خطأ تريد العمل عليه. +2. فورك مستودع Open-Science-Community-Sou-Arabia/JSquarto إلى حساب GitHub الخاص بك. +3. استنساخ المستودع المتشابك على جهازك المحلي. - ```bash - git clone https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto + “`باش + نسخة git https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto ``` -4. Sync the fork, to avoid merge conflicts. +4. مزامنة الشوك، لتجنب دمج الصراعات. - ```bash - git remote add upstream https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto - git fetch upstream - git pull upstream main - git push + “`باش + git بعد إضافة أعلى مسار https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto + Git يجلب أعلى مجرى + Git سحب الرئيسية + دفعة git ``` -5. Create a new branch with your GitHub username as its name. +5. إنشاء فرع جديد مع اسم المستخدم الخاص بك GitHub كاسم له. - ```bash - git checkout -b + “`باش + Git الدفع -b ``` -It is not mandatory to name the new branch with your GitHub username, but it is a good practice to do so, as long as the name of the branch is clear and concise, you can name it whatever you want. +ليس إلزامياً تسمية الفرع الجديد باسم مستخدم GitHub الخاص بك، ولكن من الممارسات الجيدة القيام بذلك. طالما أن اسم الفرع واضح وموجز، يمكنك تسميته ما تريده. -6. Make your changes on this new branch. -7. Commit your changes with a clear commit message. +6. قم بإجراء التغييرات الخاصة بك على هذا الفرع الجديد. +7. قم بإجراء التغييرات الخاصة بك مع رسالة التزام واضحة. - ```bash - git add . - git commit -m "Clear and concise commit message" + “`باش + git يضاف + git الالتزام -m "رسالة التزام واضحة وموجزة" ``` -8. Push your changes to your forked repository. +8. قم بدفع التغييرات الخاصة بك إلى مستودع الشوكات الخاص بك. - ```bash - git push origin + “`باش + دفعة منشأ git ``` -9. Go to the [Open-Science-Community-Saudi-Arabia/JSquarto](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto) repository on GitHub, and you should see a message suggesting to create a new pull request. Click on it. -10. To raise the PR choose the PR template and fill it with the required information. The PR template is a set of questions that you need to answer to make it easier for the maintainers to review your pull request. you can find the PR template [here](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/blob/main/.github/PULL_REQUEST_TEMPLATE.md) +9. انتقل إلى مستودع [Open-Science-Community-Saudi-Arabia/JSquarto](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto) على GitHub، ويجب أن ترى رسالة تقترح إنشاء طلب سحب جديد. انقر عليها. +10. لإثارة كلمة المرور ، اختر قالب "PR" وملأه بالمعلومات المطلوبة. قالب PR هو مجموعة من الأسئلة التي تحتاج إلى الإجابة عليها لجعل من الأسهل على المشرفين مراجعة طلب السحب الخاص بك. يمكنك العثور على قالب PR [here](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/blob/main/.github/PUL_REQUEST_TEMPLATE.md) -11. Add a clear and concise title and description for your pull request, explaining the changes you made. +11. إضافة عنوان ووصف واضحين وموجزين لطلب السحب الخاص بك، وشرح التغييرات التي أجريتها. -12. Submit your pull request, and wait for the maintainers to review your changes. +12. قم بتقديم طلب السحب الخاص بك، وانتظر المشرفين لمراجعة التغييرات الخاصة بك. -Congratulations! You've just made a pull request to the Open-Science-Community-Saudi-Arabia/JSquarto repository. +تهانينا! لقد قمت للتو بتقديم طلب سحب إلى مستودع Open-Science-Community-Sou-Arabia/JSquarto From ea5b23e1ee59bab95cee49021e0ffe9231c88ba6 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 14:26:46 +0100 Subject: [PATCH 47/61] New translations environment_setup.qmd (Arabic, Saudi Arabia) --- .../tutorials/environment_setup.qmd.ar.qmd | 76 +++++++++---------- 1 file changed, 38 insertions(+), 38 deletions(-) diff --git a/translations/ar/docs/chapters/tutorials/environment_setup.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/environment_setup.qmd.ar.qmd index e6c41bde..fc1ee52d 100644 --- a/translations/ar/docs/chapters/tutorials/environment_setup.qmd.ar.qmd +++ b/translations/ar/docs/chapters/tutorials/environment_setup.qmd.ar.qmd @@ -1,75 +1,75 @@ -### Environment_setup +### البيئة_إعداد --- -title: 'Environment Setup' +title: 'إعداد البيئة' --- -#### Prerequisites (#environment-setup) -Before testing the tool locally, ensure you have the following prerequisites installed on your system: -- Node.js and npm (Node Package Manager) -- Git (optional, if cloning the repository) +#### المتطلبات المسبقة (#environment-setup) +قبل اختبار الأداة محلياً، تأكد من وجود الشروط المسبقة التالية مثبتة على النظام الخاص بك: +- Node.js و npm (مدير الحزمة العقدية) +- Git (اختياري، إذا استنساخ المستودع) -#### Installation -To test the tool locally, follow these steps: +#### التثبيت +لاختبار الأداة محلياً، قم باتباع الخطوات التالية: -1. Clone the repository: +1. استنساخ المستودع: - ```bash - git clone https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto + “`باش + نسخة git https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto ``` -2. Navigate to the projecte directory +2. انتقل إلى دليل المشروع -3. Install dependencies +3. تثبيت الإعتمادات - ```bash + “`باش npm install ``` -### Running the Tool -Once the dependencies are installed, you can paste the files in the JS files or folder in the `/source_files` directory you can run the tool using the following command +### تشغيل الأداة +بمجرد تثبيت التبعيات ، يمكنك لصق الملفات في ملفات JS أو المجلد في دليل `/source_files` يمكنك تشغيل الأداة باستخدام الأمر التالي -1. To generate the documentation run the following command +1. لإنشاء الوثائق قم بتشغيل الأمر التالي - ```bash - npm run doc:generate + “`باش + npm تشغيل doc:generate ``` - This will extract the JSDoc comments from the js files and write them to their corresponding Quarto Markdown files. + هذا سوف يستخرج تعليقات JSDoc من ملفات js و يكتبها إلى ملفات Quarto Markdown المقابلة. - You can choose to specify the directory where the `source_files` are, to do this run + يمكنك اختيار تحديد الدليل حيث 'source_files' ، للقيام بهذا التشغيل - ```bash - npm run doc:generate --source= + “`باش + npm تشغيل doc:generate --source= ``` - It also supports addition of custom tutorials, to do this add the .qmd files for the tutorials in the `/tutorials` directory + كما أنه يدعم إضافة دروس مخصصة، للقيام بذلك إضافة ملفات .qmd للدروس في دليل `/tutorials` - The generated `.qmd` files can be found in the `/docs/chapters` folder + الملفات التي تم إنشاؤها `.qmd` يمكن العثور عليها في مجلد `/docs/chapters` - This command may vary depending on the workflow you choose, you may want to create the docs files in other languages too. To do this you can run the command below + قد يختلف هذا الأمر تبعاً لسير العمل الذي تختاره، قد ترغب في إنشاء ملفات المستندات بلغات أخرى أيضاً. للقيام بذلك يمكنك تشغيل الأمر أدناه - ```bash - npm run doc:generate languages=en,ar,es include_localized_versions --source= + “`باش + npm تشغيل doc:generate languages=en,ar,es include_localized_versions --source= ``` - This will generate the documentation in English, Arabic and Spanish. You can add more languages by separating them with a comma. (This doesn't actually translate the documentation, it just creates a copy of the documentation and renames it to the specified language). To integrate with a translation service, you can use the [Crowdin](https://crowdin.com/) service. + وسيصدر هذا التقرير الوثائق باللغات الإسبانية والإنكليزية والعربية. يمكنك إضافة المزيد من اللغات عن طريق فصلها بفاصلة. (هذا لا يترجم الوثائق في الواقع، بل يقوم فقط بإنشاء نسخة من الوثائق ويعاد تسميتها إلى اللغة المحددة). للتكامل مع خدمة الترجمة، يمكنك استخدام خدمة [Crowdin](https://crowdin.com/). - For more information on the available workflows see the guide here @sec-workflows + وللحصول على مزيد من المعلومات عن سير العمل المتاح، انظر الدليل هنا @sec-workflow -2. To preview the generated documentation run +2. لمعاينة الوثائق التي تم إنشاؤها قيد التشغيل - ```bash - npm run doc:preview + “`باش + npm تشغيل doc:preview ``` - The docs are previewed with quarto, so make sure to have quarto already installed + يتم معاينة المستندات مع quarto، لذا تأكد من تثبيت quarto مسبقاً -3. You can choose to generate and preview in one go, to do this run the command below +3. يمكنك اختيار إنشاء ومعاينة في ذهب واحد، للقيام بهذا تشغيل الأمر أدناه - ```bash - npm run build --source= + “`باش + npm تشغيل البناء --source= ``` - This will generate the documentation, preview with quarto and open a link to preview the docs + سيؤدي هذا إلى إنشاء الوثائق، ومعاينة مع quarto وفتح رابط لمعاينة المستندات From ebfeac4c8cf79f591c45f93c623a62167b98fe90 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 14:26:48 +0100 Subject: [PATCH 48/61] New translations adding_tutorials.qmd (Arabic, Saudi Arabia) --- .../how_to/adding_tutorials.qmd.ar.qmd | 86 +++++++++---------- 1 file changed, 43 insertions(+), 43 deletions(-) diff --git a/translations/ar/docs/chapters/tutorials/how_to/adding_tutorials.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/how_to/adding_tutorials.qmd.ar.qmd index 8b934f22..ba47d3ab 100644 --- a/translations/ar/docs/chapters/tutorials/how_to/adding_tutorials.qmd.ar.qmd +++ b/translations/ar/docs/chapters/tutorials/how_to/adding_tutorials.qmd.ar.qmd @@ -1,67 +1,67 @@ -###Adding-tutorials +###إضافة دروس -### Tutorials -Tutorials are a great way to teach people how to use your project. They are a step-by-step guide that walks the user through a specific task or concept. Tutorials are a great way to get people up and running with your project, and to help them understand how to use it. +### دروس +الدروس هي طريقة رائعة لتعليم الناس كيفية استخدام مشروعك. وهي دليل تدريجي يمشي المستخدم من خلال مهمة أو مفهوم محدد. الدروس هي طريقة رائعة لجعل الناس يستكملون مشروعك، ولمساعدتهم على فهم كيفية استخدامه. -### How tutorials are written -Tutorials are written in Quarto markdown. Quarto is a markdown language that is designed to be easy to write and read, and to be easy to convert to other formats. Quarto is a superset of markdown, so any markdown file is a valid quarto file. Quarto adds a few features to markdown to make it easier to write tutorials. Some of the features include: +### كيفية كتابة الدروس +يتم كتابة الدروس في علامة كوارتو. كوارتو هي لغة الدرج المصممة لتكون سهلة الكتابة والقراءة، وسهلة التحويل إلى صيغ أخرى. كوارتو عبارة عن مجموعة متميزة من الـ markdown، لذا فإن أي ملف markdown هو ملف ربع ساري المفعول. يضيف كونارتو بعض الميزات إلى المميزات لأسفل لجعلها أسهل لكتابة الدروس. وتشمل بعض المعالم ما يلي: -- The ability to include code and output in the same file -- The ability to include code from other files -- Adding metadata / images and other content to the file +- القدرة على تضمين الكود و الإخراج في نفس الملف +- القدرة على تضمين التعليمات البرمجية من الملفات الأخرى +- إضافة بيانات التعريف / الصور وغيرها من المحتوى إلى الملف -### Folder to write the tutorial -By default, tutorials are written in the `/tutorials` folder. This is the folder where all the tutorials are stored. Each tutorial is stored in a separate folder, and the folder name is the name of the tutorial. Inside the folder, there are serveral `.qmd` files that contains the tutorial contents. +### مجلد لكتابة البرنامج التعليمي +بشكل افتراضي، يتم كتابة الدروس في المجلد `/tutorials`. هذا هو المجلد حيث يتم تخزين جميع الدروس. يتم تخزين كل برنامج تعليمي في مجلد منفصل، واسم المجلد هو اسم البرنامج التعليمي. داخل المجلد، هناك ملفات ser `.qmd` التي تحتوي على محتويات البرنامج التعليمي. -### Configuring the tutorial -There is also a `config.json` file that contains the configuration for the tutorial. The `config.json` file is used to structure how the tutorial is displayed in terms of the order of the tutorial, the title, the description, and the grouping of the tutorial. +### تكوين البرنامج التعليمي +هناك أيضا ملف 'config.json' الذي يحتوي على تكوين البرنامج التعليمي. `تشكيلة'. ملف son` يستخدم لهيكلة كيفية عرض البرنامج التعليمي من حيث ترتيب البرنامج التعليمي، العنوان والوصف وتجميع البرنامج التعليمي. -Below is an example of a `config.json` file: +فيما يلي مثال لملف `config.json': ```json { - "contributing": { - "title": "Contributing to the project", - "children": { - "improving_documentation": { - "title": "Improving documentation" + "المساهمة": { + "title": "المساهمة في المشروع"، + "الأطفال": { + "Improving_documentation": { + العنوان : "تحسين التوثيق" }, "raising_issues": { - "title": "Raising issues" + العنوان: "إثارة المشاكل" }, "raising_pr": { - "title": "Raising pull requests" + "عنوان": "رفع طلبات الجذب" } } }, "project_structure": { - "title": "Project structure" + "عنوان": "بنية المشروع" }, "environment_setup": { - "title": "Environment Setup" + "العنوان": "إعداد البيئة" }, - "changelog": { - "title": "Change log" + "سجل التغييرات": { + "title": "سجل التغيير" }, - "localization": { - "title": "Localization" + "التوطين": { + "عنوان": "التعريب " }, - "how_to": { - "title": "How to's", - "children": { + "How_to ": { + "title": "كيف يمكن"، + "الأطفال": { "setting_default_readme": { - "title": "Setting default README" + العنوان "title": "ضبط الرحلة الافتراضية" }, "adding_tutorials": { - "title": "Adding tutorials" + "title": "إضافة دروس" }, "specifying_source_files": { - "title": "Specifying source files" + "title": "تحديد الملفات المصدرة" }, "starting_a_new_build": { - "title": "Starting a new build" + "title": "بدء بناء جديد" } } } @@ -69,21 +69,21 @@ Below is an example of a `config.json` file: ``` -In the example above, the `config.json` file contains a list of tutorials and the order in which they should be displayed. The `config.json` file also contains the title of the tutorial and the description of the tutorial. +في المثال الوارد أعلاه، يحتوي ملف `config.json` على قائمة من الدروس التعليمية والترتيب الذي ينبغي عرضها فيه. يحتوي ملف `config.json` أيضًا على عنوان البرنامج التعليمي ووصف البرنامج التعليمي. -The `config.json` file also contains a list of children for each tutorial. This is used to group tutorials together. For example, in the example above, the `contributing` tutorial has three children: `improving_documentation`, `raising_issues`, and `raising_pr`. This groups the three tutorials together under the `contributing` tutorial. +يحتوي ملف `config.json` أيضًا على قائمة للأطفال لكل برنامج تعليمي. يستخدم هذا لتجميع الدروس معا. فعلى سبيل المثال، في المثال الوارد أعلاه، فإن البرنامج التعليمي ”المساهم“ له ثلاثة أطفال: 'تحسين الوثائق`، و 'raising_issues`، و 'raising_pr`. هذا يجمع الدروس الثلاثة معاً تحت دروس "المساهمة". -### Grouping tutorials -Tutorials can be grouped together using the `config.json` file. This is useful for organizing tutorials into categories. For example, you might want to group all the tutorials related to contributing to the project together, or all the tutorials related to setting up the environment together. This makes it easier for users to find the tutorials they are interested in. +### دروس التجميع +يمكن تجميع الدروس معا باستخدام ملف `config.json'. هذا مفيد لتنظيم الدروس في فئات. على سبيل المثال، قد ترغب في تجميع جميع الدروس المتعلقة بالمساهمة في المشروع معا، أو جميع الدروس المتعلقة بتهيئة البيئة معاً. هذا يجعل من الأسهل للمستخدمين العثور على الدروس التي يهتمون بها. -In the example above, the `config.json` file groups the tutorials into categories such as `contributing`, `project_structure`, `environment_setup`, `changelog`, `localization`, and `how_to`. Each of these categories contains a list of tutorials, and each tutorial contains a list of children. This allows you to organize the tutorials in a way that makes sense for your project. +في المثال الوارد أعلاه، الملف `config.json` يجمع الدروس في فئات مثل `contributing` و`project_structure` و`environment_setup` و`changelog` و`localization` و`how_to`. ويحتوي كل من هذه الفئات على قائمة بالدروس، ويحتوي كل درس على قائمة بالأطفال. هذا يسمح لك بتنظيم الدروس بطريقة منطقية لمشروعك. -In this tutorial, we learned how to write tutorials in Quarto markdown, and how to configure the `config.json` file to structure how the tutorial is displayed. We also learned how to group tutorials together using the `config.json` file. This allows you to organize the tutorials in a way that makes sense for your project, and makes it easier for users to find the tutorials they are interested in. +في هذا البرنامج التعليمي، تعلمنا كيفية كتابة الدروس في Quarto markdown، وكيفية تكوين `config. ملف son` لهيكلة كيفية عرض البرنامج التعليمي. تعلمنا أيضا كيفية تجميع الدروس معا باستخدام ملف `config.json'. هذا يسمح لك بتنظيم الدروس بطريقة منطقية لمشروعك، ويجعل من الأسهل للمستخدمين العثور على الدروس التي يهتمون بها. Summary - - How tutorials are written - - Format for writing tutorials - - How to write a tutorial - - Folder to write the tutorial + - كيفية كتابة الدروس + - تنسيق لكتابة الدروس + - كيفية كتابة برنامج تعليمي + - مجلد لكتابة البرنامج التعليمي From c83b78c20f6a70f5681db5a6d75ac2d8e630c985 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 14:26:49 +0100 Subject: [PATCH 49/61] New translations starting_the_project.qmd (Arabic, Saudi Arabia) --- .../how_to/starting_the_project.qmd.ar.qmd | 122 +++++++++--------- 1 file changed, 61 insertions(+), 61 deletions(-) diff --git a/translations/ar/docs/chapters/tutorials/how_to/starting_the_project.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/how_to/starting_the_project.qmd.ar.qmd index da3aa1be..23a1e314 100644 --- a/translations/ar/docs/chapters/tutorials/how_to/starting_the_project.qmd.ar.qmd +++ b/translations/ar/docs/chapters/tutorials/how_to/starting_the_project.qmd.ar.qmd @@ -1,24 +1,24 @@ -###Starting-the-project +###بدء المشروع -### Starting the project environment +### بدء بيئة المشروع -Before you start, make sure you have the following installed on your machine: +قبل البدء، تأكد من تثبيت ما يلي على جهازك: - [Quarto](https://quarto.org/docs/get-started/index.html) - [Node.js](https://nodejs.org/en/download/) -- [Yarn](https://yarnpkg.com/getting-started/install) or [NPM](https://www.npmjs.com/get-npm) -- [Typescript](https://www.typescriptlang.org/download) (optional - Only required if the files you're working with are in typescript) +- [Yarn](https://yarnpkg.com/getting-started/install) أو [NPM](https://www.npmjs.com/get-npm) +- [Typescript](https://www.typescriptlang.org/download) (اختياري - فقط إذا كانت الملفات التي تعمل معها موجودة في النص النصي -### Steps -1. Environment Setup - Refer to environment setup guide for more details [See here](#environment-setup) +### خطوات +1. إعداد البيئة + الرجوع إلى دليل إعداد البيئة لمزيد من التفاصيل [انظر هنا](#environment-setup) -2. For cases where you are working with a project that uses typescript, you will need to compile the typescript files to javascript. To do this, run the following command in the terminal: - ```bash +2. في الحالات التي تعمل فيها مع مشروع يستخدم الكتابة، سوف تحتاج إلى تجميع ملفات الكتابة إلى جافا سكريبت. للقيام بذلك، قم بتشغيل الأمر التالي في المحطة الطرفية: + “`باش tsc -b ``` - Make sure to direct the transpiled files to the correct directory. You can do this by updating the `tsconfig.json` file to include the `outDir` property. For example: + تأكد من توجيه الملفات المنقولة إلى الدليل الصحيح. يمكنك القيام بذلك عن طريق تحديث ملف 'tsconfig.json' ليشمل خاصية 'outDir'. وعلى سبيل المثال: ```json { "compilerOptions": { @@ -27,89 +27,89 @@ Before you start, make sure you have the following installed on your machine: } ``` -3. Start the project - ```bash - yarn run build +3. بدء المشروع + “`باش + تشغيل بناء يارن ``` - OR + أو - ```bash - npm run build + “`باش + npm تشغيل البناء ``` - This command will command will generate the documentation and also start a local quarto server. You can access the documentation by visiting the http link shown on your terminal. + سيولد هذا الأمر التوثيق وسيبدأ أيضًا خادم محلي. يمكنك الوصول إلى الوثائق عن طريق زيارة الرابط الهاتفي المعروض على المحطة الطرفية الخاصة بك. -4. Make changes to the documentation and see the changes reflect on the browser. +4. إجراء تغييرات على التوثيق ومشاهدة التغييرات تعكس على المتصفح. -5. Once you are done, you can stop the server by pressing `Ctrl + C` on your terminal. +5. بمجرد الانتهاء من ذلك، يمكنك إيقاف الخادم بالضغط على 'Ctrl + C` في المحطة الطرفية الخاصة بك. -6. To generate the documentation without starting the server, run the following command: - ```bash - npm run doc:generate +6. لإنشاء الوثائق دون بدء تشغيل الخادم، قم بتشغيل الأمر التالي: + “`باش + npm تشغيل doc:generate ``` - OR + أو - ```bash - yarn run doc:generate + “`باش + تشغيل yarn doc:generate ``` -9: To preview the documentation without starting the server, run the following command: - ```bash - npm run doc:preview +9: لمعاينة الوثائق دون بدء تشغيل الخادم، قم بتشغيل الأمر التالي: + “`باش + npm تشغيل doc:preview ``` - OR + أو - ```bash - yarn run doc:preview + “`باش + yarn تشغيل doc:preview ``` - This command will startup a quarto server to preview the already generated documentation and open it in your default browser. + سيؤدي هذا الأمر إلى بدء تشغيل خادم quarto لمعاينة الوثائق التي تم إنشاؤها بالفعل وفتحها في المتصفح الافتراضي الخاص بك. -8. To clean the generated documentation, run the following command: - ```bash - npm run doc:clean +8. لتنظيف الوثائق التي تم إنشاؤها، قم بتشغيل الأمر التالي: + “`باش + npm تشغيل doc:clean ``` - OR + أو - ```bash - yarn run doc:clean + “`باش + تشغيل yarn doc:clean ``` - This command will delete the generated documentation files. Note that this command will not delete the `/tutorials` or `/source_files directory or wherever the tutorials and source_files are stored. Only the generated documentation files will be deleted. + سيؤدي هذا الأمر إلى حذف ملفات المستندات التي تم إنشاؤها. لاحظ أن هذا الأمر لن يحذف دليل `/tutorials` أو `/source_files أو حيثما يتم تخزين الدروس و source_files. سيتم حذف ملفات المستندات التي تم إنشاؤها فقط. -You can specify the source files path by including the `--source` flag in the command. For example: -```bash -npm run build --source=./path/to/source_files +يمكنك تحديد مسار الملفات المصدر عن طريق تضمين علم `--source` في الأمر. وعلى سبيل المثال: +“`باش +npm تشغيل البناء --source=./path/to/source_files ``` -OR +أو -```bash -yarn run build --source=./path/to/source_files +“`باش +تشغيل yarn لبناء --source=./path/to/source_files ``` -You can also specify the tutorials path by including the `--tutorial` flag in the command. For example: -```bash -npm run build --tutorials=./path/to/tutorials +يمكنك أيضا تحديد مسار الدروس عن طريق تضمين علم `--البرنامج التعليمي` في الأمر. وعلى سبيل المثال: +“`باش +npm تشغيل البناء --دروس تعليمية=./path/to/tutorials ``` -Summary of commands: -- `npm run build` - Generate the documentation and start a local quarto server -- `yarn run build` - Generate the documentation and start a local quarto server -- `npm run doc:generate` - Generate the documentation without starting the server -- `yarn run doc:generate` - Generate the documentation without starting the server -- `npm run doc:preview` - Preview the generated documentation without starting the server -- `yarn run doc:preview` - Preview the generated documentation without starting the server -- `npm run doc:clean` - Delete the generated documentation files -- `yarn run doc:clean` - Delete the generated documentation files +موجز الأوامر: +- 'npm قيد الإنشاء' - إنشاء الوثائق وبدء خادم محلي للحجر +- 'yarn قيد الإنشاء' - توليد الوثائق وبدء خادم الحجر المحلي +- 'npm run doc:generate' - إنشاء الوثائق دون بدء تشغيل الخادم +- 'yarn run doc:generate' - إنشاء الوثائق دون بدء تشغيل الخادم +- 'npm تشغيل doc:preview' - معاينة الوثائق التي تم إنشاؤها دون بدء تشغيل الخادم +- 'yarn run doc:preview' - معاينة الوثائق التي تم إنشاؤها دون بدء تشغيل الخادم +- 'npm run doc:Cle' - حذف ملفات الوثائق التي تم إنشاؤها +- 'yarn run doc:Cle' - حذف ملفات الوثائق التي تم إنشاؤها -Tags -- `--source` - Specify the source files path -- `--tutorial` - Specify the tutorials path +الوسوم +- `--source` - تحديد مسار الملفات المصدر +- `--البرنامج التعليمي` - تحديد مسار الدروس From f3f1f65b25a55db52678e6d36db361b0ffe5a6fd Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 14:26:50 +0100 Subject: [PATCH 50/61] New translations usage.qmd (Arabic, Saudi Arabia) --- .../tutorials/how_to/usage.qmd.ar.qmd | 82 +++++++++---------- 1 file changed, 41 insertions(+), 41 deletions(-) diff --git a/translations/ar/docs/chapters/tutorials/how_to/usage.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/how_to/usage.qmd.ar.qmd index 9a917d27..61192991 100644 --- a/translations/ar/docs/chapters/tutorials/how_to/usage.qmd.ar.qmd +++ b/translations/ar/docs/chapters/tutorials/how_to/usage.qmd.ar.qmd @@ -1,69 +1,69 @@ -###Usage +###الاستخدام -## Usage {#sec-usage} +## الاستخدام {#sec-usage} -### Custom CLI arguments -The CLI arguments are used to customize the behavior of the JSquarto tool. These bespoke arguments enable you to tailor the documentation generation process to suit your specific requirements. By leveraging these arguments, you can enhance the efficiency and effectiveness of the documentation generation process, thereby streamlining your workflow and optimizing your documentation output. +### حجج CLI مخصصة +يتم استخدام حجج CLI لتخصيص سلوك أداة JSquarto هذه الحجج المفصلة تمكنك من تصميم عملية توليد الوثائق بما يناسب متطلباتك المحددة. وبالاستفادة من هذه الحجج، يمكنك تعزيز كفاءة وفعالية عملية توليد الوثائق، مما يؤدي إلى تبسيط سير العمل الخاص بك وتحسين إنتاج الوثائق الخاصة بك. -Some of the custom CLI arguments supported by JSquarto include: -1. `--source`: Source files are pivotal components containing the comments that JSquarto utilizes to generate comprehensive documentation. Specifies the directory containing the source files to be documented. These files can be can be written in various languages supported by JSquarto, such as JavaScript, TypeScript, and JSX. By default, JSquarto will check for the `/source_files` 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. +بعض حجج CLI المخصصة المدعومة من JSquarto تشمل: +1. `--source`: الملفات المصدرية هي مكونات محورية تحتوي على التعليقات التي تستخدمها JSquarto لإنتاج وثائق شاملة. يحدد الدليل الذي يحتوي على الملفات المصدر التي سيتم توثيقها. يمكن كتابة هذه الملفات بلغات مختلفة مدعومة من JSquarto، مثل JavaScript و TypeScript و JSX. بشكل افتراضي، سيقوم JSquarto بالتحقق من الدليل `/source_files` داخل هيكل المشروع الخاص بك لتحديد موقع هذا الملف المصدر. ومع ذلك، لديك المرونة لتعيين دليل بديل من خلال خيار '--source'. -2. `--tutorial`: Specifies the directory containing the tutorial files to be included in the documentation. This argument allows you to incorporate tutorial content into your documentation, providing additional context and guidance for users. +2. `--البرنامج التعليمي`: يحدد الدليل الذي يحتوي على ملفات البرنامج التعليمي المراد تضمينها في الوثائق. هذه الحجة تسمح لك بإدماج المحتوى التعليمي في وثائقك، وتوفير سياق إضافي وإرشادات للمستخدمين. -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. +3. `--الناتج`: يحدد دليل المخرجات حيث سيتم تخزين الوثائق التي تم إنشاؤها. بشكل افتراضي، سيقوم JSquarto بحفظ الوثائق في دليل `/docs` داخل هيكل المشروع الخاص بك. ومع ذلك، يمكنك تخصيص موقع الإخراج عن طريق تحديد دليل بديل من خلال خيار '--خرج`. -4. `languages`: Specifies the languages to be supported in the documentation. This argument enables you to generate documentation in multiple languages, catering to a diverse user base. For example, `languages=en,fr,es` specifies English, French, and Spanish as the supported languages. +4. 'اللغات`: يحدد اللغات التي ينبغي دعمها في الوثائق. هذه الحجة تمكنك من توليد الوثائق بلغات متعددة، وتغذي قاعدة متنوعة من المستخدمين. فعلى سبيل المثال، تحدد `languages=en,fr,es' اللغات الانكليزية والفرنسية والإسبانية بوصفها اللغات المدعومة. -5. `include_localized_versions`: Specifies whether to include localized versions of the generated documentation. For example, if specified, JSquarto will generate seperate files for each specified language. +5. `include_localized_versions`: يحدد ما إذا كان ينبغي إدراج إصدارات موضعية من الوثائق التي تم إنشاؤها. على سبيل المثال، إذا تم تحديدها، سيقوم JSquarto بإنشاء ملفات منفصلة لكل لغة محددة. -### Configuration -The `config.json` file in the root directory of the project is used to store the configuration settings for the JSquarto tool. This file contains the default settings for the documentation generation process, such as the source files directory, tutorial files directory, output directory, and supported languages. You can modify these settings to customize the documentation generation process according to your preferences. This file is useful for cases where the cli arguments specified are multiple and you want to avoid specifying them each time you run the tool. +### تكوين +ملف `config.json' في الدليل الجذر للمشروع يستخدم لتخزين إعدادات التكوين لأداة JSquarto . يحتوي هذا الملف على الإعدادات الافتراضية لعملية توليد الوثائق، مثل دليل الملفات المصدر، ودليل الملفات التعليمية، ودليل الإخراج، واللغات المعتمدة. يمكنك تعديل هذه الإعدادات لتخصيص عملية توليد الوثائق وفقا لتفضيلاتك. هذا الملف مفيد للحالات التي تكون فيها حجج القبائل المحددة متعددة وترغب في تجنب تحديدها في كل مرة تقوم فيها بتشغيل الأداة. -The `config.json` file contains the following fields: -1. `sourceDirectory`: Specifies the directory containing the source files to be documented. By default, this field is set to `/source_files` within the project structure. This is the same as the `--source` CLI argument. +يحتوي ملف `config.json` على الحقول التالية: +1. `المصدر`: يحدد الدليل الذي يحتوي على الملفات المصدرية التي يتعين توثيقها. بشكل افتراضي، يتم تعيين هذا الحقل إلى '/source_files' داخل بنية المشروع. وهذا هو نفس حجة CI '--source'. -2. `tutorialDirectory`: Specifies the directory containing the tutorial files to be included in the documentation. By default, this field is set to `/tutorial_files` within the project structure. This is the same as the `--tutorial` CLI argument. +2. `دليل الدروس`: يحدد الدليل الذي يحتوي على ملفات الدرس التعليمي التي ستدرج في الوثائق. بشكل افتراضي، يتم تعيين هذا الحقل إلى '/tutorial_files' داخل بنية المشروع. هذا هو نفس حجة الـ CLI `--tutorial'. -3. `outputDirectory`: Specifies the output directory where the generated documentation will be stored. By default, this field is set to `/docs` within the project structure. This is the same as the `--output` CLI argument. +3. 'دليل النواتج`: يحدد دليل المخرجات حيث سيتم تخزين الوثائق التي تم إنشاؤها. بشكل افتراضي، يتم تعيين هذا الحقل إلى `/docs` داخل بنية المشروع. هذا هو نفس حجة CI '--output'. -### Usage -To utilize these custom CLI arguments, simply append them to the JSquarto command when executing the tool. For example: +### الاستخدام +لاستخدام حجج CLI المخصصة هذه، ببساطة قم بإلحاقها بأمر JSquarto عند تنفيذ الأداة. وعلى سبيل المثال: -To specify the source files directory: -```bash -npm run doc:generate --source=/path/to/your/source/files +لتحديد دليل ملفات المصدر: +“`باش +npm تشغيل doc:generate --source=/path/to/your/source/files ``` -To specify the tutorial files directory: -```bash -npm run doc:generate --tutorial=/path/to/your/tutorial/files +لتحديد دليل ملفات البرنامج التدريبي: +“`باش +npm تشغيل doc:generate --tutorial=/path/to/your/tutorial/files ``` -To specify the output directory: -```bash -npm run doc:generate --output=/path/to/your/output/directory +لتحديد دليل الإخراج: +“`باش +npm تشغيل doc:generate --output=/path/to/your/output/directory ``` -To specify the supported languages: -```bash -npm run doc:generate languages=en,fr,es +لتحديد اللغات المعتمدة: +“`باش +npm تشغيل doc:generate languages=en,fr,es ``` -This will only add the languages to the config file (_quarto.yml) and not generate the documentation in the specified languages. This is important for cases where an external tool like Crowdin will be used to translate the documentation and generate the files in the specified languages. +سيؤدي هذا فقط إلى إضافة اللغات إلى ملف التكوين (_quarto.yml) وعدم إنشاء الوثائق باللغات المحددة. هذا مهم للحالات التي تستخدم فيها أداة خارجية مثل كراودِن لترجمة الوثائق وإنشاء الملفات باللغات المحددة. -To include localized versions of the generated documentation: -```bash -npm run doc:generate include_localized_versions languages=en,fr,es +لإدراج النسخ المترجمة للوثائق التي تم إنشاؤها: +“`باش +npm تشغيل doc:generate include_localized_versions languages=en,fr,es ``` -This will generate the documentation in the specified languages and also add the languages to the config file (_quarto.yml). +سيؤدي هذا إلى توليد الوثائق باللغات المحددة وأيضاً إضافة اللغات إلى ملف التكوين (_quarto.yml). -Note: If you intend to `include_localized_versions`, you must also specify the `languages` argument to indicate the supported languages for the documentation. +ملاحظة: إذا كنت تنوي 'include_localized_versions`، فيجب عليك أيضا تحديد حجة 'اللغات` للإشارة إلى اللغات المؤيدة للوثائق. -By leveraging these custom CLI arguments, you can tailor the documentation generation process to meet your specific needs and preferences, thereby enhancing the quality and usability of your documentation output. +من خلال الاستفادة من حجج CLI المخصصة هذه، يمكنك تصميم عملية توليد الوثائق لتلبية احتياجاتك وتفضيلاتك المحددة، وبالتالي تعزيز جودة وإمكانيات استخدام نواتج الوثائق الخاصة بك. -### Leveraging TypeScript in Source Files -When utilizing TypeScript within your project, it's advisable to transpile your TypeScript source files into JavaScript before initiating the JSquarto process. This recommendation stems from the fact that JSquarto lacks intrinsic support for TypeScript syntax. Once you've transpiled your TypeScript files into JavaScript, you can seamlessly execute JSquarto on the resultant JavaScript files to generate comprehensive documentation. +### الاستفادة من TypeScript في ملفات المصدر +عند استخدام TypeScript ضمن مشروعك، من المستصوب تحويل ملفات مصدر TypeScript إلى JavaScript قبل بدء عملية JSquarto . تنبع هذه التوصية من حقيقة أن JSquarto تفتقر إلى الدعم الجوهري لجملة TypeScript. بمجرد أن تقوم بنقل ملفات TypeScript الخاصة بك إلى JavaScript، يمكنك تنفيذ JSquarto بسلاسة على ملفات JavaScript الناتجة لإنشاء وثائق شاملة. -Integrating TypeScript Transpilation -Prior to executing JSquarto, ensure to transpile your TypeScript source files into JavaScript using your preferred transpiler, such as TypeScript Compiler (tsc). This step ensures compatibility with JSquarto's documentation generation process, thereby facilitating a smooth and efficient +دمج نقل TypeScript +قبل تنفيذ JSquarto، تأكد من تحويل ملفات مصدر TypeScript إلى JavaScript باستخدام المحول المفضل، مثل TypeScript Compiler (tsc). وتكفل هذه الخطوة التواؤم مع عملية توليد الوثائق في JSquarto، مما ييسر سلاسة وكفاءة From 26fef9ae79defea6ffbff8a4444c7bfb9ab64c98 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 14:26:51 +0100 Subject: [PATCH 51/61] New translations workflows.qmd (Arabic, Saudi Arabia) --- .../tutorials/how_to/workflows.qmd.ar.qmd | 102 +++++++++--------- 1 file changed, 51 insertions(+), 51 deletions(-) diff --git a/translations/ar/docs/chapters/tutorials/how_to/workflows.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/how_to/workflows.qmd.ar.qmd index dd89f16b..d115c94a 100644 --- a/translations/ar/docs/chapters/tutorials/how_to/workflows.qmd.ar.qmd +++ b/translations/ar/docs/chapters/tutorials/how_to/workflows.qmd.ar.qmd @@ -1,104 +1,104 @@ -###Workflows +###سير العمل -### Workflows {#sec-workflows} -There are different workflows that can be adopted to optimize the documentation generation process using JSquarto. +### سير العمل {#sec-workflows} +هناك مختلف سير العمل التي يمكن اعتمادها لتحسين عملية توليد الوثائق باستخدام JSquarto. -1. Doc generation -2. Doc generation with manual transalation -3. Doc generation with crowdin translation +1. توليد دوك +2. توليد دوك مع نقل يدوي +3. توليد Doc مع ترجمة crowdin -### Doc generation -This workflow involves generating documentation in a single language. The process is straightforward and involves executing JSquarto on the source files to generate comprehensive documentation in the specified language. This workflow is ideal for projects targeting a specific language audience and seeking to streamline the documentation generation process. +### توليد دوك +وينطوي سير العمل هذا على توليد الوثائق بلغة واحدة. وهذه العملية مباشرة وتنطوي على تنفيذ JSquarto على ملفات المصدر لتوليد وثائق شاملة باللغة المحددة. ويعد تدفق العمل هذا مثاليا بالنسبة للمشاريع التي تستهدف جمهورا لغويا محددا وتسعى إلى تبسيط عملية إعداد الوثائق. -#### STEPS -1. To do this, simply execute the JSquarto command with the desired custom CLI arguments, such as `--source` and `languages`, to specify the source files directory and supported languages, respectively. For example: +#### ستابس +1. للقيام بذلك، ببساطة تنفيذ أمر JSquarto مع الحجج المطلوبة ل CLI، مثل '--source' و 'languages' لتحديد دليل الملفات المصدر واللغات المدعومة، على التوالي. وعلى سبيل المثال: - ```bash - npm run doc:generate --source=/path/to/your/source/files + “`باش + npm تشغيل doc:generate --source=/path/to/your/source/files ``` -### Doc generation with manual translation -For manual translation of the documentation, you can generate the documentation in multiple languages and then manually translate the content into the desired languages. For this workflow, we use [babelquarto](https://docs.ropensci.org/babelquarto/) which helps to preview the documentation in multiple languages. Although this doesn't translate the content, it provides a preview of the documentation in the specified languages, enabling you to manually translate the content. +### توليد دوك مع ترجمة يدوية +من أجل الترجمة اليدوية للوثائق، يمكنك إنتاج الوثائق بلغات متعددة ثم ترجمة المحتوى يدوياً إلى اللغات المرغوبة. لسير العمل هذا، نستخدم [babelquarto](https://docs.ropensci.org/babelquarto/) الذي يساعد على معاينة الوثائق بلغات متعددة. على الرغم من أن هذا لا يترجم المحتوى، فإنه يوفر معاينة للوثائق باللغات المحددة، مما يتيح لك ترجمة المحتوى يدوياً. -#### Steps -1. Generate the documentation in multiple languages using JSquarto with the `languages` argument to specify the supported languages. For example: +#### الخطوات +1. توليد الوثائق بلغات متعددة باستخدام JSquarto مع حجة "اللغات" لتحديد اللغات المعتمدة. وعلى سبيل المثال: - ```bash - npm run doc:generate languages=en,fr,es include_localized_versions --source=/path/to/your/source/files + “`باش + npm تشغيل doc:generate languages=en,fr,es include_localized_versions --source=/path/to/your/source/files ``` -Note: Ensure to include the `include_localized_versions` argument to generate copies of the documentation in the specified languages. If they are not included, only the default language documentation will be generated. But the languages config will only be added to the config (_quarto.yml) file. +ملاحظة: تأكد من إدراج حجة 'include_localized_versions` لإنتاج نسخ من الوثائق باللغات المحددة. إذا لم تكن مشمولة، سيتم إنشاء وثائق اللغة الافتراضية فقط. ولكن سيتم إضافة تكوين اللغات إلى ملف التكوين (_quarto.yml) فقط. -2. Manually translate the content in the generated documentation files for each language. You can leverage tools such as Google Translate or professional translation services to facilitate the translation process. +2. ترجمة المحتوى يدويا في ملفات الوثائق التي تم إنشاؤها لكل لغة. يمكنك استخدام أدوات مثل ترجمة جوجل أو خدمات الترجمة المهنية لتسهيل عملية الترجمة. -3. Download RStudio and install the `babelquarto` package from CRAN. This package is used to preview the documentation in multiple languages. You can install the package using the following command: +3. قم بتحميل RStudio وتثبيت حزمة 'babelquarto' من CRAN. يتم استخدام هذه الحزمة لمعاينة الوثائق بلغات متعددة. يمكنك تثبيت الحزمة باستخدام الأمر التالي: - ```R + “`R install.packages('babelquarto', repos = c('https://ropensci.r-universe.dev', 'https://cloud.r-project.org')) ``` -4. Open the generated doc folder in RStudio, navigate to the console and set the working directory to the doc folder. +4. افتح مجلد دوك الذي تم إنشاؤه في RStudio، انتقل إلى وحدة التحكم وتعيين دليل العمل إلى مجلد doc - ```R + “`R project_dir <- "/home/richie/Desktop/repos/oscsa/JSquarto/docs" ``` -5. Preview the documentation in multiple languages using the `babelquarto` package. For example, to preview the documentation in English, French, and Spanish, execute the following command: +5. معاينة الوثائق بلغات متعددة باستخدام حزمة 'babelquarto'. وعلى سبيل المثال، لتنفيذ الأمر التالي من أجل معاينة الوثائق باللغات الانكليزية والفرنسية والإسبانية: - ```R + “`R babelquarto::render_book(file.path(parent_dir, project_dir)) ``` -6. As at the time of writing this, there are minor issues with navigating the previewed documentation in different languages. To fix this temporarily, run +6. وحتى وقت كتابة هذا التقرير، كانت هناك مسائل طفيفة تتعلق بالتنقل في الوثائق المعاد النظر فيها بلغات مختلفة. لإصلاح هذا مؤقتاً، قم بتشغيل - ```bash - npm run fix:all languages=en,fr,es + “`باش + npm تشغيل إصلاح: جميع اللغات=en,fr,es ``` - Note: The `fix:all` script is a custom script that fixes the navigation issues in the previewed documentation. This script is used to update the navigation links in the previewed documentation to enable seamless navigation between the different languages. And the languages specified in the script should match the languages specified in the `languages` argument during the documentation generation process. + ملاحظة: البرنامج النصي "إصلاح:all" هو برنامج نصي مخصص يصلح مشاكل التنقل في الوثائق المعاينة. يستخدم هذا البرنامج النصي لتحديث روابط التنقل في الوثائق المعاينة لتمكين التنقل السلس بين اللغات المختلفة. واللغات المحددة في النص ينبغي أن تتطابق مع اللغات المحددة في حجة "اللغات" أثناء عملية إعداد الوثائق. -7. You can navigate to the `/docs/_book` directory to view the previewed documentation in multiple languages. The previewed documentation provides a comprehensive overview of the content in each language, enabling you to verify the translations and ensure the accuracy and quality of the documentation. +7. يمكنك الانتقال إلى دليل `/docs/_book` لعرض الوثائق المعاينة بلغات متعددة. وتوفر الوثائق التي تمت معاينتها استعراضا شاملا لمحتوى كل لغة. يمكنك من التحقق من الترجمات وضمان دقة وجودة الوثائق. -### Doc generation with crowdin translation -For automated translation of the documentation, you can leverage the Crowdin platform to facilitate the translation process. Crowdin is a cloud-based translation management platform that enables you to automate the translation of content into multiple languages. By integrating Crowdin with JSquarto, you can streamline the translation process and generate comprehensive documentation in various languages efficiently. +### توليد دوك مع ترجمة الحشود +للترجمة الآلية للوثائق، يمكنك الاستفادة من منصة كرودن لتسهيل عملية الترجمة. كراودِن هو منصة إدارة الترجمة القائمة على السحابة والتي تمكنك من أتمتة ترجمة المحتوى إلى لغات متعددة. من خلال دمج كراودِن مع JSquarto، يمكنك تبسيط عملية الترجمة وإنشاء وثائق شاملة بلغات مختلفة بكفاءة. -#### Steps -1. Generate the documentation in multiple languages using JSquarto with the `languages` argument to specify the supported languages. For example: +#### الخطوات +1. توليد الوثائق بلغات متعددة باستخدام JSquarto مع حجة "اللغات" لتحديد اللغات المعتمدة. وعلى سبيل المثال: - ```bash - npm run doc:generate languages=en,fr,es --source=/path/to/your/source/files + “`باش + npm تشغيل doc:generate languages=en,fr,es --source=/path/to/your/source/files ``` - Note that the `include_localized_versions` argument is not required for this workflow, as Crowdin will handle the translation process. And generate the different files for each language. + لاحظ أن حجة "include_localized_versions" ليست مطلوبة لسير العمل هذا، لأن كراودِن سوف يتعامل مع عملية الترجمة. وإنشاء ملفات مختلفة لكل لغة. -2. Integrate Crowdin with JSquarto to automate the translation process. To integrate Crowdin, you need to create a Crowdin project and configure the project settings to enable the automatic translation of the documentation. You can refer to the [Crowdin Github integration documentation](https://support.crowdin.com/github-integration/#:~:text=Open%20your%20project%20and%20go%20to%20the%20Integrations,drop-down%20list%20to%20integrate%20via%20your%20GitHub%20account) for detailed instructions on setting up a project and configuring the translation settings. -On Crowdin, you can set up how the translated files will be named, make sure it follows the format `original_file_name.locale.extension` e.g `index.en.qmd`, `index.fr.qmd`, `index.es.qmd` +2. دمج كراودِن مع JSquarto لأتمتة عملية الترجمة. لدمج كراودن، تحتاج إلى إنشاء مشروع كراودِن وتكوين إعدادات المشروع لتمكين الترجمة التلقائية للوثائق. يمكنك الرجوع إلى [Crowdin Github Integration](https://support.crowdin. om/github-integration/#:~:text=فتح%20الخاص بك%20project%20and%20go%20to%20%20INtegrt، قرص أسفل%20list%20to%20integrate%20عن طريق%20الخاص بك%20GitHub%20a) للحصول على تعليمات مفصلة بشأن إعداد مشروع وتكوين إعدادات الترجمة. +في كراودين، يمكنك إعداد كيفية تسمية الملفات المترجمة، والتأكد من أنها تتبع تنسيق `original_file_name.locale.extension` على سبيل المثال `index.en.qmd`، `index.fr.qmd`، `index.es.qmd` -3. Once you've configured the Crowdin project settings, you can proceed to render the documentation in multiple languages using the `babelquarto` package. This step enables you to preview the documentation in different languages before initiating the translation process. You can leverage the `babelquarto` package to preview the documentation in multiple languages, as described in the previous workflow. To do this open the generated doc folder in RStudio, navigate to the console and set the working directory to the doc folder. +3. بمجرد تكوين إعدادات مشروع Crowdin ، يمكنك المضي قدما في تقديم الوثائق بلغات متعددة باستخدام حزمة 'babelquarto'. هذه الخطوة تمكنك من معاينة الوثائق بلغات مختلفة قبل بدء عملية الترجمة. يمكنك استخدام حزمة 'babelquarto' لمعاينة الوثائق بلغات متعددة، كما هو مبين في تدفق العمل السابق. للقيام بهذا فتح مجلد doc الذي تم إنشاؤه في RStudio، انتقل إلى وحدة التحكم وتعيين دليل العمل إلى مجلد doc - ```R + “`R project_dir <- "/home/richie/Desktop/repos/oscsa/JSquarto/docs" ``` - Preview the documentation in multiple languages using the `babelquarto` package. For example, to preview the documentation in English, French, and Spanish, execute the following command: + معاينة الوثائق بلغات متعددة باستخدام حزمة 'babelquarto'. وعلى سبيل المثال، لتنفيذ الأمر التالي من أجل معاينة الوثائق باللغات الانكليزية والفرنسية والإسبانية: - ```R + “`R babelquarto::render_book(file.path(parent_dir, project_dir)) ``` -4. After rendering the book, the html files will be generated and set in the `/docs/_book` directory. You can then serve the book using any static server like `http-server` or `live-server` to preview the documentation in multiple languages. Alternatively, you can run the following command to serve the book: +4. بعد تقديم الكتاب، سيتم إنشاء ملفات html وتعيينها في دليل `/docs/_book'. يمكنك بعد ذلك خدمة الكتاب باستخدام أي خادم ثابت مثل 'http-server' أو 'live-server' لمعاينة الوثائق بلغات متعددة. بدلاً من ذلك، يمكنك تشغيل الأمر التالي لخدمة الكتاب: - ```bash - npm run serve + “`باش + npm تشغيل الخدمة ``` - After serving the book, you can navigate to the specified URL to view the documentation in multiple languages. In some cases you may notice that the navigation links are not working as expected. To fix this, run the following command: + بعد تقديم الكتاب، يمكنك الانتقال إلى عنوان URL المحدد لعرض الوثائق بلغات متعددة. في بعض الحالات قد تلاحظ أن روابط التنقل لا تعمل كما هو متوقع. لإصلاح هذا، قم بتشغيل الأمر التالي: - ```bash - npm run fix:all languages=en,fr,es + “`باش + npm تشغيل إصلاح: جميع اللغات=en,fr,es ``` -This workflow uses JSquarto to generate the documentation, and Crowdin to initiate the translation process which creates the translated files in the specified languages, lastly the `babelquarto` package to preview the documentation in multiple languages. +يستخدم سير العمل هذا JSquarto لتوليد الوثائق، و Crowdin لبدء عملية الترجمة التي تنشئ الملفات المترجمة باللغات المحددة، أخيرا حزمة 'babelquarto' لمعاينة الوثائق بلغات متعددة. From a6b0049af8db76eba8351b56fa87843623d0e70d Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 14:26:52 +0100 Subject: [PATCH 52/61] New translations localization.qmd (Arabic, Saudi Arabia) --- .../tutorials/localization.qmd.ar.qmd | 56 +++++++++---------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/translations/ar/docs/chapters/tutorials/localization.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/localization.qmd.ar.qmd index 563c07c5..50abfbfe 100644 --- a/translations/ar/docs/chapters/tutorials/localization.qmd.ar.qmd +++ b/translations/ar/docs/chapters/tutorials/localization.qmd.ar.qmd @@ -1,48 +1,48 @@ -### Localization +### التعريب --- -title: Localization +title: التعريب --- -Localization is the process of adapting software to meet the language, cultural, and other specific requirements of a particular locale or market. It is an essential aspect of software development that helps to ensure that products are accessible to users around the world. Localization involves translating software content such as user interfaces, text, and multimedia, among others, to make it appropriate for different regions. +والتوطين هو عملية تكييف البرمجيات لتلبية الاحتياجات اللغوية والثقافية وغيرها من المتطلبات المحددة لموقع أو سوق بعينه. وهو جانب أساسي من جوانب تطوير البرمجيات يساعد على ضمان وصول المنتجات إلى المستعملين في جميع أنحاء العالم. وينطوي التعريب على ترجمة محتوى البرمجيات مثل الوصلات البينية للمستعملين، والنصوص، والوسائط المتعددة، من بين وسائل أخرى، لجعلها مناسبة لمختلف المناطق. -Crowdin is a powerful localization platform that provides a range of features for efficient software localization. In this section, we will discuss localization, translation, and how Crowdin works as a localization platform. We will also highlight the importance of localization in software development and how it can impact the success of a product. Finally, we will explore the benefits of using Crowdin as a localization platform and the advantages it offers compared to other alternatives. +كرودن هو منصة توطين قوية توفر مجموعة من الميزات لتوطين البرمجيات بكفاءة. في هذا القسم، سنناقش التعريب والترجمة وكيفية عمل كرودن كمنصة للتعريب. وسوف نسلط الضوء أيضا على أهمية إضفاء الطابع المحلي على تطوير البرمجيات وكيف يمكن أن يؤثر ذلك على نجاح المنتج. أخيراً، سوف نستكشف فوائد استخدام كراودِن كمنصة للتوطين والمزايا التي يقدمها مقارنة بالبدائل الأخرى. -## What is Localization? +## ما هو التعريب ؟ -Localization is the process of adapting a product or service to meet the language, cultural, and other requirements of a specific country or region. This involves translating the content of the product, such as text, images, and audio, into the local language and adapting it to meet the cultural requirements of the target market. +والتوطين هو عملية تكييف منتج أو خدمة لتلبية الاحتياجات اللغوية والثقافية وغيرها من المتطلبات لبلد أو منطقة بعينها. هذا يتضمن ترجمة محتوى المنتج، مثل النصوص، والصور، والصوت، والصوت، • استخدام اللغة المحلية وتكييفها لتلبية المتطلبات الثقافية للسوق المستهدفة. -Localization is important in software development because it helps to make the product more accessible to a global audience and improve user experience. By translating the content into the local language, developers can reach a wider audience and make it easier for users to understand and use the product. +والتوطين مهم في تطوير البرمجيات لأنه يساعد على جعل المنتج أيسر منالا للجمهور العالمي وتحسين تجربة المستخدم. من خلال ترجمة المحتوى إلى اللغة المحلية، يمكن للمطورين الوصول إلى جمهور أوسع وجعل من الأسهل على المستخدمين فهم المنتج واستخدامه. -## What is Translation? +## ما هي الترجمة؟ -Translation is the process of converting written or spoken content from one language to another. This process involves understanding the original content and reproducing it in the target language, while taking into account any cultural or linguistic differences. +الترجمة هي عملية تحويل المحتوى المكتوب أو المنطوق من لغة إلى أخرى. وتنطوي هذه العملية على فهم المحتوى الأصلي واستنساخه باللغة المستهدفة، مع مراعاة أي اختلافات ثقافية أو لغوية. -Translation is important in software development because it allows developers to make their products accessible to a global audience. By translating the content into the local language, developers can reach a wider audience and make it easier for users to understand and use the product. +والترجمة مهمة في تطوير البرمجيات لأنها تسمح للمطورين بجعل منتجاتهم متاحة للجمهور العالمي. من خلال ترجمة المحتوى إلى اللغة المحلية، يمكن للمطورين الوصول إلى جمهور أوسع وجعل من الأسهل على المستخدمين فهم المنتج واستخدامه. -## Crowdin as a Localization Platform +## كراودِن كمنصة للتعريب -Crowdin is a localization platform that helps developers to manage the localization process for their products. It provides a range of features that make it easier for developers to translate their products and collaborate with translators. +كراودِن هو منصة توطين تساعد المطورين على إدارة عملية توطين منتجاتهم. يوفر مجموعة من الميزات التي تجعل من الأسهل على المطورين ترجمة منتجاتهم والتعاون مع المترجمين. -Crowdin features include: +تشمل ميزات كراودِن: -- Translation management -- Collaboration tools -- Quality assurance -- Integration with development tools +- إدارة الترجمة +- أدوات التعاون +- ضمان الجودة +- التكامل مع أدوات التنمية - Crowdsourcing -- In-context translations -- Machine translation +- الترجمات في السياق +- الترجمة الآلية -Using Crowdin for localization has several advantages, including: +استخدام كراودِن للتعريب له عدة مزايا، بما في ذلك: -- Easier management of translation projects -- Faster turnaround times for translations -- Improved translation quality -- Collaboration with translators from around the world -- Integration with development tools, such as GitHub and Bitbucket -- Ability to use machine translation for faster translations +- إدارة أسهل لمشاريع الترجمة +- أوقات دوران أسرع للترجمة +- تحسين جودة الترجمة +- التعاون مع المترجمين من جميع أنحاء العالم +- التكامل مع أدوات التنمية، مثل GitHub و Bitbucket +- القدرة على استخدام الترجمة الآلية لترجمات أسرع -## Conclusion +## استنتاج -Localization is an important aspect of software development, and using a platform like Crowdin can help make the process easier and more efficient. With Crowdin, developers can manage translation projects, collaborate with translators, and improve the quality of translations. By using a combination of localization and translation, developers can make their products more accessible to a global audience and improve user experience. +التعريب هو جانب هام من تطوير البرمجيات، واستخدام منصة مثل كراودِن يمكن أن يساعد على جعل العملية أسهل وأكثر كفاءة. مع كراودن، يمكن للمطورين إدارة مشاريع الترجمة، والتعاون مع المترجمين، وتحسين جودة الترجمات. باستخدام مزيج من التعريب والترجمة، يمكن للمطورين جعل منتجاتهم أيسر منالا للجمهور العالمي وتحسين تجربة المستخدم. From cb09c7d45f199ecc4d247f08d53cd270e13045e7 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 14:26:53 +0100 Subject: [PATCH 53/61] New translations project_structure.qmd (Arabic, Saudi Arabia) --- .../tutorials/project_structure.qmd.ar.qmd | 52 +++++++++---------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/translations/ar/docs/chapters/tutorials/project_structure.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/project_structure.qmd.ar.qmd index 0bcc3272..124f0abe 100644 --- a/translations/ar/docs/chapters/tutorials/project_structure.qmd.ar.qmd +++ b/translations/ar/docs/chapters/tutorials/project_structure.qmd.ar.qmd @@ -1,17 +1,17 @@ -### Project_structure +### بنية المشروع --- -title: Project structure +title: بنية المشروع --- -#### Project file structure -JSQuarto is structured as follows: +#### بنية ملف المشروع +وفيما يلي هيكل الرابطة اليابانية للتعاون التقني: -```bash +“`باش ├── src -│ ├── intefaces -│ │ ├── index.ts + - وصية + - فهارس │ ├── utils │ │ ├── codeconstruct.ts │ │ ├── component.ts @@ -19,29 +19,29 @@ JSQuarto is structured as follows: │ │ ├── logger.ts │ │ ├── parser.ts │ │ ├── string.ts -│ │ ├── writer.ts -│ ├── tutorials -│ │ ├── contributing/ -│ │ ├── how_to/ -│ │ ├── environment_setup.qmd -│ │ ├── localization.qmd -│ │ ├── project_structure.qmd -│ │ ├── config.json + - كتاب + - دروس + -- مساهمة/ + -how_to / + environment_setup.qmd + -localization.qmd + ', project_structure.qmd + )-config.json │ │ -│ ├── index.ts + - فهارس │ │ -│ ├── package.json -│ ├── package-lock.json -│ ├── .prettierrc + ', package.json + ', package-lock.json + .prettierrc ``` -The `API` directory contains the source code for JSQuarto. The `API` directory is structured as follows: +يحتوي دليل "API" على رمز المصدر لـ JSQuarto. وينظم دليل "API" على النحو التالي: -- `src/interfaces` - Contains the all type/intefaces definitions for the project. -- `src/utils` - Contains the all utility functions for the project. These utility functions are used to perform various tasks such as parsing, writing, and logging. -- `src/tutorials` - Contains the all tutorials for the project. These tutorials are written in Quarto Markdown format. Note that the `config.json` file is used to define how the tutorials are structured. -- `src/index.ts` - The main entry point for the project. -- `src/package.json` - The project's package.json file. -- `src/.prettierrc` - The project's prettier configuration file. +- 'src/interfaces' - يحتوي على جميع تعاريف النوع/العناوين للمشروع. +- 'src/utils' - يحتوي على جميع وظائف المنفعة للمشروع. وتستخدم هذه الوظائف المفيدة لأداء مهام مختلفة مثل الوقوف والكتابة وقطع الأخشاب. +- 'src/tutorials' - يحتوي على جميع الدروس للمشروع. هذه الدروس مكتوبة بتنسيق Quarto Markdown. لاحظ أن ملف `config.json` يستخدم لتحديد كيفية هيكلة الدروس. +- 'src/index.ts' - المدخل الرئيسي للمشروع. +- 'src/package.json' - ملف حزمة المشروع؛ +- 'src/.prettierrc' - ملف التكوين المسبق للمشروع. From b795f49adf439237ea2746f5d14066ff9023ce4d Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 14:26:54 +0100 Subject: [PATCH 54/61] New translations index.md (Arabic, Saudi Arabia) --- translations/ar/docs/index.md.ar.md | 36 ++++++++++++++--------------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/translations/ar/docs/index.md.ar.md b/translations/ar/docs/index.md.ar.md index 3d2d939e..e19481df 100644 --- a/translations/ar/docs/index.md.ar.md +++ b/translations/ar/docs/index.md.ar.md @@ -1,33 +1,33 @@ -# Welcome to JSQuarto Documentation +# مرحبا بكم في وثائق JSQuarto -## About +## حول -JSQuarto is a tool designed to generate JavaScript package API reference documentation using Markdown and Quarto. It serves as an alternative to JSDoc, providing a simpler and more flexible approach for documenting JavaScript code. +JSQuarto هي أداة مصممة لتوليد وثائق مرجعية لحزمة API جافا سكريبت باستخدام Markdown و Quarto. يعمل كبديل لـ JSDoc، ويوفر نهجا أبسط وأكثر مرونة لتوثيق شفرة جافا سكريبت. -## Purpose +## الغرض -The purpose of JSQuarto is to streamline the process of generating API reference documentation for JavaScript packages. By leveraging Markdown and Quarto, developers can easily create and maintain comprehensive documentation for their JavaScript projects. +الغرض من JSQuarto هو تبسيط عملية إنشاء وثائق API المرجعية لحزم جافا سكريبت. من خلال الاستفادة من Markdown و Quarto، يمكن للمطورين إنشاء وحفظ وثائق شاملة لمشاريع جافا سكريبت الخاصة بهم. -## Inspiration +## إلهام -JSQuarto draws inspiration from various documentation tools and methodologies, including:
+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.
+- [JSDoc](https://jsdoc.app/): JSDoc هو أداة شائعة لتوليد وثائق API من كود مصدر جافا سكريبت.
+- [Quarto](https://quarto.org/): Quarto هي أداة مؤلفة ونشر وثيقة متنوعة تدعم تنسيقات Markdown, LaTeX, and R Markdown.
+- [Sphinx](https://www.sphinx-doc.org/): Sphinx هو أداة لتوليد الوثائق تستخدم على نطاق واسع في مجتمع Python.
-## Localization and Translation +## التعريب والترجمة -JSQuarto is committed to supporting localization and translation of generated documentation. We are planning to integrate Crowdin, a localization management platform, to facilitate translation efforts. This will enable users to present the generated QMD files in multiple languages, making documentation accessible to a wider audience. +وشركة JSQuarto ملتزمة بدعم توطين وترجمة الوثائق التي تم إنشاؤها. نحن نخطط لدمج كراودن، وهي منصة لإدارة التعريب ، لتسهيل جهود الترجمة. وهذا سيمكن المستخدمين من تقديم ملفات QMD التي تم إنشاؤها بلغات متعددة، مما يجعل الوثائق متاحة لجمهور أوسع. -## Contributing Organization +## المنظمة المساهمة -JSQuarto is developed and maintained by the [Open Science Community Saudi Arabia](https://github.com/Open-Science-Community-Saudi-Arabia). Our mission is to promote open science practices and foster collaboration among researchers and developers in Saudi Arabia. +تم تطوير وصيانة JSQuarto من قبل [المجتمع العلمي المفتوح في المملكة العربية السعودية] (https://github.com/Open-Science-Community-Saudi-Arabia). وتتمثل مهمتنا في تعزيز الممارسات العلمية المفتوحة وتعزيز التعاون بين الباحثين والمطورين في المملكة العربية السعودية. -## Getting Started +## بدء العمل -To start using JSQuarto, visit the [GitHub repository](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto) for installation instructions and usage documentation. +لبدء استخدام JSQuarto، قم بزيارة [GitHub repository](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto) للحصول على تعليمات التثبيت ووثائق الاستخدام. -## Feedback and Support +## الملاحظات والدعم -If you have any questions, feedback, or need support, please [open an issue](https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/issues) on GitHub or [join our community](https://github.com/Open-Science-Community-Saudi-Arabia) for assistance. +إذا كان لديك أي أسئلة، أو ردود فعل، أو تحتاج إلى دعم، يرجى [فتح مشكلة] (https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto/issues) على GitHub أو [الانضمام إلى مجتمعنا](https://github.com/Open-Science-Community-Saudi-Arabia) للحصول على المساعدة. From 8e474f3cec140b5df9edee6f29e852f9aaf1377e Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 21:00:21 +0100 Subject: [PATCH 55/61] New translations improving_documentation.qmd (Arabic, Saudi Arabia) --- .../improving_documentation.qmd.ar.qmd | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/translations/ar/docs/chapters/tutorials/contributing/improving_documentation.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/contributing/improving_documentation.qmd.ar.qmd index 0e9dd095..7645edfd 100644 --- a/translations/ar/docs/chapters/tutorials/contributing/improving_documentation.qmd.ar.qmd +++ b/translations/ar/docs/chapters/tutorials/contributing/improving_documentation.qmd.ar.qmd @@ -15,8 +15,8 @@ 1. تعليقات الترميز: أضف تعليقات JSDoc مباشرة فوق عناصر التعليمات البرمجية التي تريد توثيقها. استخدام /\*_ ... _/ بناء الجملة للإشارة إلى كتلة تعليقات JSDoc . 2. وظائف التوثيق: استخدام وسوم JSDoc لوصف معلمات الدالة، قيم الإرجاع، ومعلومات إضافية. العلامات مثل @param و @returns و @description شائعة الاستخدام لهذا الغرض. العلامات المخصصة المهمة الأخرى هي @category و @subcategory، هذه العلامات تساعد على هيكلة الوثائق التي تم إنشاؤها في فصول. وستكون جميع الوحدات تحت `فئة فرعية` تحت فصل واحد، وسيتطابق اسم الفصل مع الاسم المعين لـ `الفئة الفرعية`. - الفكرة الرئيسية حول الفئتين @category و @subcategory هي السماح للفصول المتداخلة على سبيل المثال يمكن أن يحتوي الفصل الأول ألف على فصول فرعية أخرى (الفصل ألف (أ). () الفصل أب - الفصل ألف) مع كل فصل من هذه الفصول الفرعية وحدات خاصة بها. - لاحظ أن هذا هو مستويين فقط من التعقيد، حيث أن الفصل ألف هو الفئة @والفئة الفرعية @@ ستكون هي الفصول الأخرى. نعتزم في البداية تنفيذ مستويين من الفصول المتداخلة، ولكن هذا في وقت كتابة هذا الربع لا يسمح إلا لمستوى واحد من التعبيد (١). ، يمكن أن يكون لديك فصل واحد فقط مع عدم وجود فصول فرعية، نتيجة لذلك، فقط الفئات الفرعية @سوف يتم عرضها كفصول في الوثيقة المقدمة. + الفكرة الرئيسية حول الفئتين @category و @subcategory هي السماح للفصول المتداخلة على سبيل المثال يمكن أن يحتوي الفصل الأول ألف على فصول فرعية أخرى (الفصل ألف (أ). + لاحظ أن هذا هو مستويين فقط من التعقيد، حيث أن الفصل ألف هو الفئة @والفئة الفرعية @@ ستكون هي الفصول الأخرى. نعتزم في البداية تنفيذ مستويين من الفصول المتداخلة، ولكن هذا في وقت كتابة هذا الربع لا يسمح إلا لمستوى واحد من التعبيد (١). 3. فئات التوثيق: بالنسبة للصفوف الدراسية، استخدم تعليقات JSDoc لتوفير الأوصاف، وخصائص الصف المستندي، وطرائق فصل المستند. العلامات مثل @clas، @propers، و @method شائعة الاستخدام في هذا السياق. @@ -28,7 +28,7 @@ ### استخدام JSDoc لكتابة الوثائق -كما يمكن استخدام JSDoc بما يتجاوز إصدار الوثائق الرمزية نظام بناء الجملة والعلامة المرن لديه يجعله أداة قيمة لكتابة جوانب أخرى من وثائق مشروعك، مثل الدروس والأدلة والمواد المرجعية. +المواد المرجعية: يمكن استخدام تعليقات JSDoc لتوفير معلومات إضافية في المواد المرجعية. كما يمكن استخدام JSDoc بما يتجاوز إصدار الوثائق الرمزية نظام بناء الجملة والعلامة المرن لديه يجعله أداة قيمة لكتابة جوانب أخرى من وثائق مشروعك، مثل الدروس والأدلة والمواد المرجعية. لاستخدام JSDoc لكتابة الوثائق، يرجى النظر في النُهج التالية: @@ -36,7 +36,7 @@ 2. أمثلة مضمنة: استخدم تعليقات JSDoc لتضمينها أمثلة على الرموز المضمنة التي توضح استخدام الدوال أو الصفوف أو الوحدات. ويمكن استخدام هذه الأمثلة كمادة تعليمية وكمرجع سريع للمطورين. -3. المواد المرجعية: يمكن استخدام تعليقات JSDoc لتوفير معلومات إضافية في المواد المرجعية. مثل شرح أنماط التصميم، أو تحديد أفضل الممارسات، أو توضيح المفاهيم المعقدة. وسوم Leverage JSDoc مثل @example أو @see لربط الموارد أو أمثلة التعليمات البرمجية ذات الصلة. +3. مثل شرح أنماط التصميم، أو تحديد أفضل الممارسات، أو توضيح المفاهيم المعقدة. وسوم Leverage JSDoc مثل @example أو @see لربط الموارد أو أمثلة التعليمات البرمجية ذات الصلة. 4. التكامل مع Markdown: JSDoc يدعم Markdown ضمن التعليقات، مما يسمح لك بدمج النصوص المنسقة والعناوين والقوائم وغيرها من ميزات Markdown في وثائقك. هذا يمكّنك من إنشاء محتوى أكثر جاذبية بصرياً وتنظيماً في تعليقات JSDoc الخاصة بك. @@ -68,7 +68,7 @@ Markdown هي لغة علامة خفيفة الوزن تسمح بسهولة تن من خلال هيكلة الدروس داخل مجلد "الدروس" باستخدام Markdown، يمكن للمساهمين المساهمة بدروس جديدة، تحديث الوثائق الموجودة، وضمان أن تظل الوثائق شاملة وسهلة الاستعمال. -وعموما، فإن الجمع بين `. ملفات son` ومجلد "الدروس التعليمية" يمكنان من بنية وثائق منظمة تنظيماً جيداً ويمكن الوصول إليها، مما يسمح للمستخدمين بالتنقل واستكشاف وثائق منصة JSQuarto بسهولة. +ملفات son` ومجلد "الدروس التعليمية" يمكنان من بنية وثائق منظمة تنظيماً جيداً ويمكن الوصول إليها، مما يسمح للمستخدمين بالتنقل واستكشاف وثائق منصة JSQuarto بسهولة. #### نظرة عامة على ملفات `config.json` @@ -211,10 +211,10 @@ Markdown هي لغة علامة خفيفة الوزن تسمح بسهولة تن - ملف التكوين 'json' موجود في المجلد 'دروس التعليمية' - يحتوي مجلد "الدروس" على مجلدات فرعية تمثل أقسام أو فئات مختلفة من الدروس. - كل قسم أو مجلد فئة، مثل 'المشرفين` و 'المساهمة`، يحتوي على ملفات '.qmd' لدروس فردية. - + الهيكل المتداخل يسمح لك بتنظيم الدروس هرمياً ، مما يجعل من الأسهل التنقل والبحث عن دروس محددة استناداً إلى موضوعها أو فئتها. من المهم ملاحظة أن بنية البرنامج التعليمي لا تسمح إلا بمستوى واحد من التعش. هذا يعني أنه يمكنك الحصول على الأقسام الرئيسية ودروسها، ولكن لا يمكنك إنشاء المزيد من المجلدات المتداخلة داخل الدروس. -من خلال اتباع هيكل المجلدات هذا وما يرافقه `. md` ملفات نظرة عامة، يمكنك بسهولة تحديد التسلسل الهرمي والعلاقات بين الدروس، السماح لك بإنشاء دروس متداخلة وتنظيم وثائقك بطريقة منطقية ومنظمة. +md` ملفات نظرة عامة، يمكنك بسهولة تحديد التسلسل الهرمي والعلاقات بين الدروس، السماح لك بإنشاء دروس متداخلة وتنظيم وثائقك بطريقة منطقية ومنظمة. From f79d0f03d8ce4f2e3cc84d18194924a19d34e2eb Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 21:00:22 +0100 Subject: [PATCH 56/61] New translations raising_issues.qmd (Arabic, Saudi Arabia) --- .../chapters/tutorials/contributing/raising_issues.qmd.ar.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/translations/ar/docs/chapters/tutorials/contributing/raising_issues.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/contributing/raising_issues.qmd.ar.qmd index 312dbbb8..8a4ef2f8 100644 --- a/translations/ar/docs/chapters/tutorials/contributing/raising_issues.qmd.ar.qmd +++ b/translations/ar/docs/chapters/tutorials/contributing/raising_issues.qmd.ar.qmd @@ -25,7 +25,7 @@ وفي وصف القضايا، قدم أكبر قدر ممكن من التفاصيل بشأن المسألة أو الاقتراح. قم بإدراج خطوات لتكرار المشكلة إذا كان ذلك منطبقاً، وأي معلومات ذات صلة أو سياق يمكن أن يساعد الآخرين على فهم المسألة بشكل أفضل. ### استخدام تسميات المشكلة -يتم استخدام تسميات الإصدار لتصنيف وتنظيم المشكلات في مشروع مفتوح المصدر. ويمكن أن تساعد المساهمين على تحديد نوع المشكلة ومركزها بسرعة. ويمكن أيضا أن يساعد المشرفين على تحديد أولويات القضايا المتراكمة في المشروع وإدارتها. +يتم استخدام تسميات الإصدار لتصنيف وتنظيم المشكلات في مشروع مفتوح المصدر. ويمكن أيضا أن يساعد المشرفين على تحديد أولويات القضايا المتراكمة في المشروع وإدارتها. عند إثارة مشكلة، تأكد من اختيار التسمية المناسبة التي تصف المشكلة على أفضل وجه. على سبيل المثال، إذا كنت تبلغ عن خطأ، قد تستخدم علامة "الخطأ". إذا كنت تقترح ميزة جديدة أو تحسين، قد تستخدم تسمية "التحسينات". From 04ef99a6b3bfd38ad58e0eaaa4c760202d53a705 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 21:00:23 +0100 Subject: [PATCH 57/61] New translations raising_pr.qmd (Arabic, Saudi Arabia) --- .../docs/chapters/tutorials/contributing/raising_pr.qmd.ar.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/translations/ar/docs/chapters/tutorials/contributing/raising_pr.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/contributing/raising_pr.qmd.ar.qmd index f0b93ec1..fdec6e7c 100644 --- a/translations/ar/docs/chapters/tutorials/contributing/raising_pr.qmd.ar.qmd +++ b/translations/ar/docs/chapters/tutorials/contributing/raising_pr.qmd.ar.qmd @@ -26,7 +26,7 @@ “`باش Git الدفع -b ``` -ليس إلزامياً تسمية الفرع الجديد باسم مستخدم GitHub الخاص بك، ولكن من الممارسات الجيدة القيام بذلك. طالما أن اسم الفرع واضح وموجز، يمكنك تسميته ما تريده. +ليس إلزامياً تسمية الفرع الجديد باسم مستخدم GitHub الخاص بك، ولكن من الممارسات الجيدة القيام بذلك. 6. قم بإجراء التغييرات الخاصة بك على هذا الفرع الجديد. 7. قم بإجراء التغييرات الخاصة بك مع رسالة التزام واضحة. From 25bfc76bddb922e511c9ced2bfebbf3a40d744de Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 21:00:25 +0100 Subject: [PATCH 58/61] New translations adding_tutorials.qmd (Arabic, Saudi Arabia) --- .../chapters/tutorials/how_to/adding_tutorials.qmd.ar.qmd | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/translations/ar/docs/chapters/tutorials/how_to/adding_tutorials.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/how_to/adding_tutorials.qmd.ar.qmd index ba47d3ab..049ad451 100644 --- a/translations/ar/docs/chapters/tutorials/how_to/adding_tutorials.qmd.ar.qmd +++ b/translations/ar/docs/chapters/tutorials/how_to/adding_tutorials.qmd.ar.qmd @@ -16,7 +16,7 @@ ### تكوين البرنامج التعليمي -هناك أيضا ملف 'config.json' الذي يحتوي على تكوين البرنامج التعليمي. `تشكيلة'. ملف son` يستخدم لهيكلة كيفية عرض البرنامج التعليمي من حيث ترتيب البرنامج التعليمي، العنوان والوصف وتجميع البرنامج التعليمي. +هناك أيضا ملف 'config.json' الذي يحتوي على تكوين البرنامج التعليمي. ملف son` يستخدم لهيكلة كيفية عرض البرنامج التعليمي من حيث ترتيب البرنامج التعليمي، العنوان والوصف وتجميع البرنامج التعليمي. فيما يلي مثال لملف `config.json': @@ -78,7 +78,7 @@ في المثال الوارد أعلاه، الملف `config.json` يجمع الدروس في فئات مثل `contributing` و`project_structure` و`environment_setup` و`changelog` و`localization` و`how_to`. ويحتوي كل من هذه الفئات على قائمة بالدروس، ويحتوي كل درس على قائمة بالأطفال. هذا يسمح لك بتنظيم الدروس بطريقة منطقية لمشروعك. -في هذا البرنامج التعليمي، تعلمنا كيفية كتابة الدروس في Quarto markdown، وكيفية تكوين `config. ملف son` لهيكلة كيفية عرض البرنامج التعليمي. تعلمنا أيضا كيفية تجميع الدروس معا باستخدام ملف `config.json'. هذا يسمح لك بتنظيم الدروس بطريقة منطقية لمشروعك، ويجعل من الأسهل للمستخدمين العثور على الدروس التي يهتمون بها. +في هذا البرنامج التعليمي، تعلمنا كيفية كتابة الدروس في Quarto markdown، وكيفية تكوين `config. تعلمنا أيضا كيفية تجميع الدروس معا باستخدام ملف `config.json'. هذا يسمح لك بتنظيم الدروس بطريقة منطقية لمشروعك، ويجعل من الأسهل للمستخدمين العثور على الدروس التي يهتمون بها. Summary - كيفية كتابة الدروس From a5f4b03cb282ec0c7d4004bc1d32143a5fc08726 Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 21:00:26 +0100 Subject: [PATCH 59/61] New translations usage.qmd (Arabic, Saudi Arabia) --- translations/ar/docs/chapters/tutorials/how_to/usage.qmd.ar.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/translations/ar/docs/chapters/tutorials/how_to/usage.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/how_to/usage.qmd.ar.qmd index 61192991..a2c505dd 100644 --- a/translations/ar/docs/chapters/tutorials/how_to/usage.qmd.ar.qmd +++ b/translations/ar/docs/chapters/tutorials/how_to/usage.qmd.ar.qmd @@ -3,7 +3,7 @@ ## الاستخدام {#sec-usage} ### حجج CLI مخصصة -يتم استخدام حجج CLI لتخصيص سلوك أداة JSquarto هذه الحجج المفصلة تمكنك من تصميم عملية توليد الوثائق بما يناسب متطلباتك المحددة. وبالاستفادة من هذه الحجج، يمكنك تعزيز كفاءة وفعالية عملية توليد الوثائق، مما يؤدي إلى تبسيط سير العمل الخاص بك وتحسين إنتاج الوثائق الخاصة بك. +يتم استخدام حجج CLI لتخصيص سلوك أداة JSquarto هذه الحجج المفصلة تمكنك من تصميم عملية توليد الوثائق بما يناسب متطلباتك المحددة. “`باش وبالاستفادة من هذه الحجج، يمكنك تعزيز كفاءة وفعالية عملية توليد الوثائق، مما يؤدي إلى تبسيط سير العمل الخاص بك وتحسين إنتاج الوثائق الخاصة بك. بعض حجج CLI المخصصة المدعومة من JSquarto تشمل: 1. `--source`: الملفات المصدرية هي مكونات محورية تحتوي على التعليقات التي تستخدمها JSquarto لإنتاج وثائق شاملة. يحدد الدليل الذي يحتوي على الملفات المصدر التي سيتم توثيقها. يمكن كتابة هذه الملفات بلغات مختلفة مدعومة من JSquarto، مثل JavaScript و TypeScript و JSX. بشكل افتراضي، سيقوم JSquarto بالتحقق من الدليل `/source_files` داخل هيكل المشروع الخاص بك لتحديد موقع هذا الملف المصدر. ومع ذلك، لديك المرونة لتعيين دليل بديل من خلال خيار '--source'. From 9a292b4e786aeb042690033ff7cd92d24014e0dc Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 21:00:27 +0100 Subject: [PATCH 60/61] New translations workflows.qmd (Arabic, Saudi Arabia) --- .../ar/docs/chapters/tutorials/how_to/workflows.qmd.ar.qmd | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/translations/ar/docs/chapters/tutorials/how_to/workflows.qmd.ar.qmd b/translations/ar/docs/chapters/tutorials/how_to/workflows.qmd.ar.qmd index d115c94a..a06673a5 100644 --- a/translations/ar/docs/chapters/tutorials/how_to/workflows.qmd.ar.qmd +++ b/translations/ar/docs/chapters/tutorials/how_to/workflows.qmd.ar.qmd @@ -55,7 +55,7 @@ ملاحظة: البرنامج النصي "إصلاح:all" هو برنامج نصي مخصص يصلح مشاكل التنقل في الوثائق المعاينة. يستخدم هذا البرنامج النصي لتحديث روابط التنقل في الوثائق المعاينة لتمكين التنقل السلس بين اللغات المختلفة. واللغات المحددة في النص ينبغي أن تتطابق مع اللغات المحددة في حجة "اللغات" أثناء عملية إعداد الوثائق. -7. يمكنك الانتقال إلى دليل `/docs/_book` لعرض الوثائق المعاينة بلغات متعددة. وتوفر الوثائق التي تمت معاينتها استعراضا شاملا لمحتوى كل لغة. يمكنك من التحقق من الترجمات وضمان دقة وجودة الوثائق. +7. يمكنك الانتقال إلى دليل `/docs/_book` لعرض الوثائق المعاينة بلغات متعددة. يمكنك من التحقق من الترجمات وضمان دقة وجودة الوثائق. @@ -71,7 +71,7 @@ لاحظ أن حجة "include_localized_versions" ليست مطلوبة لسير العمل هذا، لأن كراودِن سوف يتعامل مع عملية الترجمة. وإنشاء ملفات مختلفة لكل لغة. -2. دمج كراودِن مع JSquarto لأتمتة عملية الترجمة. لدمج كراودن، تحتاج إلى إنشاء مشروع كراودِن وتكوين إعدادات المشروع لتمكين الترجمة التلقائية للوثائق. يمكنك الرجوع إلى [Crowdin Github Integration](https://support.crowdin. om/github-integration/#:~:text=فتح%20الخاص بك%20project%20and%20go%20to%20%20INtegrt، قرص أسفل%20list%20to%20integrate%20عن طريق%20الخاص بك%20GitHub%20a) للحصول على تعليمات مفصلة بشأن إعداد مشروع وتكوين إعدادات الترجمة. +2. دمج كراودِن مع JSquarto لأتمتة عملية الترجمة. لدمج كراودن، تحتاج إلى إنشاء مشروع كراودِن وتكوين إعدادات المشروع لتمكين الترجمة التلقائية للوثائق. om/github-integration/#:~:text=فتح%20الخاص بك%20project%20and%20go%20to%20%20INtegrt، قرص أسفل%20list%20to%20integrate%20عن طريق%20الخاص بك%20GitHub%20a) للحصول على تعليمات مفصلة بشأن إعداد مشروع وتكوين إعدادات الترجمة. في كراودين، يمكنك إعداد كيفية تسمية الملفات المترجمة، والتأكد من أنها تتبع تنسيق `original_file_name.locale.extension` على سبيل المثال `index.en.qmd`، `index.fr.qmd`، `index.es.qmd` 3. بمجرد تكوين إعدادات مشروع Crowdin ، يمكنك المضي قدما في تقديم الوثائق بلغات متعددة باستخدام حزمة 'babelquarto'. هذه الخطوة تمكنك من معاينة الوثائق بلغات مختلفة قبل بدء عملية الترجمة. يمكنك استخدام حزمة 'babelquarto' لمعاينة الوثائق بلغات متعددة، كما هو مبين في تدفق العمل السابق. للقيام بهذا فتح مجلد doc الذي تم إنشاؤه في RStudio، انتقل إلى وحدة التحكم وتعيين دليل العمل إلى مجلد doc From 3c69720a925a457badb6eb2b8e0f64dedb46064b Mon Sep 17 00:00:00 2001 From: Richie <76791916+RealRichi3@users.noreply.github.com> Date: Mon, 13 May 2024 21:02:30 +0100 Subject: [PATCH 61/61] Update config.json --- config.json | 1 + 1 file changed, 1 insertion(+) diff --git a/config.json b/config.json index 4415f921..80ae7a06 100644 --- a/config.json +++ b/config.json @@ -2,6 +2,7 @@ "includeLocalizedVersion": false, "outputDirectory": "docs", "sourceDirectory": "dist", + "translationsDirectory": "translations", "tutorialDirectory": "tutorials", "languages": ["en", "ar"] }