Optimizing Workflow with Custom CLI Arguments

###Optimizing-workflow

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.

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

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:

npm run doc:generate --source=/path/to/your/source/files

To specify the tutorial files directory:

npm run doc:generate --tutorial=/path/to/your/tutorial/files

To specify the supported languages:

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:

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

Workflows

There are different workflows that can be adopted to optimize the documentation generation process using JSquarto.

Doc generation
Doc generation with manual transalation
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

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:
```
    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 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

Generate the documentation in multiple languages using JSquarto with the languages argument to specify the supported languages. For example:
```
    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.
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.
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:
```
    install.packages('babelquarto', repos = c('https://ropensci.r-universe.dev', 'https://cloud.r-project.org'))
```
Open the generated doc folder in RStudio, navigate to the console and set the working directory to the doc folder.
```
    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::render_book(file.path(parent_dir, project_dir))
```
As at the time of writing this, there are minor issues with navigating the previewed documentation in different languages. To fix this temporarily, run
```
    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.
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

Generate the documentation in multiple languages using JSquarto with the languages argument to specify the supported languages. For example:
```
    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.
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 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
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.
```
    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::render_book(file.path(parent_dir, project_dir))
```
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:
```
    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:
```
    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.