diff --git a/Writerside/dcs.tree b/Writerside/dcs.tree index b34f765..3099024 100644 --- a/Writerside/dcs.tree +++ b/Writerside/dcs.tree @@ -7,4 +7,5 @@ start-page="starter-topic.md"> - \ No newline at end of file + + diff --git a/Writerside/topics/How-to-build-test-deploy-Writerside-documentation.md b/Writerside/topics/How-to-build-test-deploy-Writerside-documentation.md new file mode 100644 index 0000000..6c8de80 --- /dev/null +++ b/Writerside/topics/How-to-build-test-deploy-Writerside-documentation.md @@ -0,0 +1,124 @@ +Here's the revised guide with the updated assumption: + +--- + +# How to Build, Test & Deploy Writerside Documentation + +In this guide, you will learn how to set up a **reusable GitHub Actions workflow** to build, test, +and deploy Writerside documentation to GitHub Pages. The reusable workflow will be installed +alongside **ESLint**, **Prettier**, and **TSConfig** in your repository using **NPM**. This process +allows you to centralize and reuse workflows across multiple repositories while ensuring consistent +code quality. + +> **Note** +> This guide assumes that you have installed `@kurocado-studio/style-guide` as a dev. dependency +> +> {style="note"} + +## Before You Start + +Make sure that: + +- You have installed the reusable workflow package (`@kurocado-studio/style-guide`) in your + repository. +- Your repository is set up with **NPM** for package management. +- You have access to the **GITHUB_TOKEN** secret in your repository. + +## How to Install and Set Up the Workflow + +Follow these steps to integrate the Writerside documentation build and deploy workflow alongside +**ESLint**, **Prettier**, and **TSConfig**. + +### 1. Create the Workflow File + +To set up the reusable Writerside workflow, you need to create a workflow file in your repository +that references the reusable workflow. + +1. **Create the workflow directory and file**: + + In your terminal, create the workflow directory and file in your repository: + + ```bash + mkdir -p .github/workflows + touch .github/workflows/call-reusable-writerside.yml + ``` + +2. **Define the reusable workflow in the YAML file**: + + Open the `.github/workflows/call-reusable-writerside.yml` file in your preferred text editor and + paste the following configuration: + + ```yaml + name: Call Writerside Reusable Workflow + + on: + push: + branches: ['main'] # Trigger on push to the main branch + workflow_dispatch: # Allows manual triggering from the Actions tab + + jobs: + call-reusable-workflow: + uses: @kurocado-studio/style-guide/gh-actions/gh-docs-actions@main # Reference the reusable workflow + with: + INSTANCE: 'Writerside/dcs' # You can override instance if needed + ARTIFACT: 'webHelpDCS2-all.zip' # Override artifact name if necessary + DOCKER_VERSION: '242.21870' # Override Docker version if needed + secrets: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Use GITHUB_TOKEN secret to authenticate + ``` + + - **INSTANCE**: This is the Writerside instance name, which you can override as needed. + - **ARTIFACT**: The name of the artifact generated by the build process, which can also be + overridden. + - **DOCKER_VERSION**: The Docker version of Writerside that will be used for the build. + - **GITHUB_TOKEN**: This is the secret token that GitHub Actions use for authentication, and it + is automatically generated by GitHub. + +3. **Commit and push the changes**: + + Once you’ve added the reusable workflow configuration, commit and push the changes to the `main` + branch: + + ```bash + git add .github/workflows/call-reusable-writerside.yml + git commit -m "Add reusable Writerside build and deploy workflow" + git push origin main + ``` + +### 2. Trigger and Monitor the Workflow + +After pushing the workflow, it will be triggered automatically if there are any changes to the +`main` branch. You can also manually trigger it from the **Actions** tab in your GitHub repository. + +#### **Trigger the workflow manually**: + +1. Go to the **Actions** tab in your repository. +2. Select the workflow labeled `Call Writerside Reusable Workflow`. +3. Click **Run workflow** to manually trigger the process. + +#### **Monitor the workflow**: + +Once the workflow is running, you can monitor its progress in the **Actions** tab. You’ll see +detailed logs of each step, including: + +- Checking out the repository. +- Building the Writerside documentation. +- Testing the documentation using Writerside Checker. +- Deploying the documentation to GitHub Pages. + +### 3. Verify the Deployment + +Once the workflow has completed successfully, your Writerside documentation will be deployed to +GitHub Pages. + +- You can verify the deployment by visiting your GitHub Pages site (you can find the link under + **Settings** > **Pages**). +- If you’re using a custom domain, ensure the domain is properly configured in the **Settings** tab + of your repository. + +## Conclusion + +By following this guide, you have successfully set up and triggered a reusable workflow for +building, testing, and deploying Writerside documentation to GitHub Pages. This process allows for +centralized workflow management across multiple repositories, ensuring consistent deployment +practices while integrating seamlessly with NPM-managed tools like ESLint, Prettier, and TSConfig. diff --git a/Writerside/writerside-config.xml b/Writerside/writerside-config.xml index 38b8c11..7e85b2b 100644 --- a/Writerside/writerside-config.xml +++ b/Writerside/writerside-config.xml @@ -1,5 +1,5 @@ - + diff --git a/package.json b/package.json index 1d447c5..682d6cc 100644 --- a/package.json +++ b/package.json @@ -12,7 +12,7 @@ }, "license": "MPL-2.0", "exports": { - "./gh-docs-actions": "./.github/workflows/deploy_docs.yml", + "./gh-actions/gh-docs-actions": "./.github/workflows/deploy_docs.yml", "./commitlint": "./src/commitlint/index.js", "./semantic-release": "./src/semantic-release/index.js", "./eslint/base": "./src/eslint/eslint.base.js",