Integrating a new project

The following sections describe how to integrate a new project into the qs-tooling-documentation website.

Environment Setup

Local development:

Copy .env.example to .env and set paths to your local repo clones
You can comment out repos you're not working on (they'll use fallback placeholder docs)

CI/CD:

No .env file needed - the Jenkinsfiles clone external repos and copy docs to the default paths (e.g., docs/magellan)
The docusaurus.config.ts fallbacks match these paths, so no env vars are required

Steps

For the sake of this example, let's assume you want to integrate the documentation of the qs-magellan project.

qs-tooling-documentation repository

Checkout the Git repository https://bitbucket.org/quatico/qs-tooling-documentation
Create a new branch from the develop branch.
Create a new folder inside the docs folder called <name-of-your-project> (e.g., docs/magellan).

Create a new intro.md file in the root of the new folder.

docs/<name-of-your-project>/intro.md
<!-- this file is used to keep the directory alive. -->
<!-- in order for a docusuaurus build to work, the directory must not be empty -->
<!-- also, this file can be used as a permanent target for links from the main page (src/pages/index.tsx) pointing to this file -->

Adjust the docusaurus.config.ts configuration to include the new project by:

Add the path resolution with fallback (near the top of the file):

docusaurus.config.ts
const pathToLocal<ProjectName>DocsFolder = path.resolve(process.env.<PROJECT>_DOCS_PATH || "docs/<name-of-your-project>");

Add the plugin config and include it in the plugins array:

docusaurus.config.ts
const <projectName>PluginConfig: PluginConfig = [
    "@docusaurus/plugin-content-docs",
    {
        id: "<name-of-your-project>",
        path: pathToLocal<ProjectName>DocsFolder,
        routeBasePath: "<name-of-your-project>",
        sidebarPath: "./sidebars/sidebar<ProjectName>.ts",
        includeCurrentVersion: !HIDE_CURRENT_VERSION,
        exclude: ["**/README.md"],
    } satisfies PluginContentDocs.Options,
];

// Add to plugins array
const plugins: PluginConfig[] = [
    ..., // existing items
    <projectName>PluginConfig,
];

Add the new project to the navBarItems array.

docusaurus.config.ts
const navBarItems: NavbarItem[] = [
 ..., // existing items
 {
     type: "docsVersion",
     docsPluginId: "<name-of-your-project>",
     position: "left",
     label: "Label for <name-of-your-project>",
 },
 // only necessary if you want to have a version dropdown in the navbar
 {
     type: "docsVersionDropdown",
     docsPluginId: "<name-of-your-project>",
     position: "left",
     to: `/<name-of-your-project>`,
 },
];

Add a version command to the package.json file.

package.json
"scripts": {
    "version:<name-of-your-project>": "pnpm run docusaurus docs:version:<name-of-your-project>"
}

(Optional) Verify locally by running the versioning script:

git clone https://bitbucket.org/quatico/<name-of-your-project>.git
cd <name-of-your-project>
../scripts/create-docs-versions-from-git-tags.sh --source-dir='docs' --target-dir='docs/<name-of-your-project>' --version-command='docusaurus docs:version:<name-of-your-project>' --branch='develop'
cd ..
pnpm run build
pnpm run serve

Adjust the .build/pipelines/continuous-build-multi/Jenkinsfile and .build/pipelines/continuous-deploy/Jenkinsfile to include the new project. Add the following snippet to the stage assemble docs. Have a look at the create-docs-versions-from-git-tags.sh script for more information on the parameters.

.build/pipelines/continuous-build-multi/Jenkinsfile
// <name-of-your-project>
container('build-container') {
    sh "echo '<name-of-your-project>' >> .gitignore"
    sh "echo '<name-of-your-project>@tmp' >> .gitignore"

    dir('<name-of-your-project>') {
        checkout([$class           : 'GitSCM',
                  branches         : [[name:'develop']],
                  userRemoteConfigs: [[credentialsId: 'atlassian-bitbucket-userpass-secret', url: 'https://bitbucket.org/quatico/<name-of-your-project>.git']]])
        sh "git config --global --add safe.directory ${WORKSPACE}/<name-of-your-project>"

        // copy released tags (adjust --num-tags once enough releases exist)
        sh """
            ../scripts/create-docs-versions-from-git-tags.sh \\
                --source-dir='docs' \\
                --target-dir='docs/<name-of-your-project>' \\
                --version-command='docusaurus docs:version:<name-of-your-project>' \\
                --num-tags=1 \\
                --tags-filter='^v[0-9]+.[0-9]+.[0-9]+\$'
        """
        // copy develop branch
        sh """
            ../scripts/create-docs-versions-from-git-tags.sh \\
                --source-dir='docs' \\
                --target-dir='docs/<name-of-your-project>' \\
                --version-command='docusaurus docs:version:<name-of-your-project>' \\
                --branch='develop'
        """
    }

    sh "rm -rf <name-of-your-project>"
}

--source-dir names the documentation folder relative to the root of the source repository. A pnpm workspace that ships its docs with a package names that package's folder, for example --source-dir='packages/qs-design-tests/docs'.

Commit and push the changes to the repository.

source repository

The following steps must be performed in a source repository (e.g., qs-magellan) for a new project to be surfaced on the documentation website.

setup & repository structure

Checkout the Git repository (e.g., https://bitbucket.org/quatico/qs-magellan).
Create a folder for the documentation, usually docs at the repository root. A pnpm workspace can keep it in the package that ships it (qs-design-tests uses packages/qs-design-tests/docs); --source-dir in the Jenkinsfile names the folder.
- All the documentation that shall be surfaced on the documentation website must be placed in this folder.
- The folder structure doesn't matter (but it will be reflected in the navigation and sidebar of the result).
- There MUST be a intro.md file in the root of the folder (the content doesn't matter). This is used to provide a direct link to the documentation on the main page of the website.
Commit and push the changes to the repository.
Ensure that the changes are part of a tagged release vX.Y.Z (e.g., v1.2.3). The versioning script accepts only this form: a candidate tag such as v1.2.3-rc.4 or a snapshot tag never becomes a version. Until the first vX.Y.Z tag exists, the script finds no tag and the build fails.

how to trigger a new build of the documentation project?

Add the following stage to the continuous-deploy Jenkinsfile of the project you want to trigger a new build for:

.build/pipelines/continuous-deploy/Jenkinsfile
stage('Trigger qs-tooling-documentation build') {
    steps {
        build job: 'cds-tooling/qs-tooling-documentation/continuous-deploy', wait: false
    }
}

how to validate any documentation changes in the source repository?

Create a new pipeline in the source repository, in its pipeline directory: .build/pipeline/validate-documentation-changes/Jenkinsfile (or .build/pipelines/… where the repository uses that name). The scriptPath of step 2 must name the same path. Use the following example as a template:

.build/pipelines/validate-documentation-changes/Jenkinsfile
// the pipeline is defined in the cloud repository as a shared library (groovy script)
// the pipeline is defined in the cloud Jenkins pipelines.groovy file
// the pipeline is triggered by 'continuous-build-branch-source' updates for all branches

// triggers the 'validate-documentation-changes' pipeline with the following inputs:
// - sourceDir: the path to the documentation to validate (in the qs-magellan repository)
def sourceDir = "docs/magellan"
// - targetDir: the name of the folder to place the documentation in the qs-tooling-documentation repository
def targetDir = "docs/magellan"
// - slackChannel: the slack channel to send messages to
def slackChannel = "#q_cds_tooling_activity"
// - projectGitUrl: the git url of the project to validate
def projectGitUrl = "https://bitbucket.org/quatico/qs-magellan.git"

validateDocumentationChanges(sourceDir, targetDir, slackChannel, projectGitUrl)

Register the pipeline in the pipelines.groovy file in the repository where the project's Jenkins configuration is located. For example, for the qs-magellan repository, the Jenkins configuration is located in the apps repository.

pipelines.groovy
 multibranchPipelineJob('cds-tooling/qs-magellan/validate-documentation-changes') {
     displayName('validate-documentation-changes')
     branchSources {
         branchSource {
             source {
                 git {
                     id('continuous-build-branch-source')
                     remote('https://bitbucket.org/quatico/qs-magellan.git')
                     credentialsId('atlassian-bitbucket-userpass-secret')
                     traits {
                         gitBranchDiscovery()
                         headWildcardFilter {
                             includes('*')
                             excludes('develop')
                         }
                     }
                 }
             }
         }
     }
     factory {
         workflowBranchProjectFactory {
             scriptPath('.build/pipeline/validate-documentation-changes/Jenkinsfile')
         }
     }
     triggers {
         periodicFolderTrigger {
             interval('1m')
         }
     }
     orphanedItemStrategy {
         defaultOrphanedItemStrategy {
             abortBuilds(true)
             pruneDeadBranches(true)
             daysToKeepStr('')
             numToKeepStr('')
         }
         discardOldItems {
             numToKeep(5)
         }
     }
 }

Merge the Job DSL change through a pull request in the repository where the Jenkins configuration is located. No Jenkins image rebuild is needed: after the merge, Jenkins restarts and its seed job creates the pipeline.
The new pipeline is now available in the Jenkins and will be triggered for all new branches.

Environment Setup​

Steps​

qs-tooling-documentation repository​

source repository​

setup & repository structure​

how to trigger a new build of the documentation project?​

how to validate any documentation changes in the source repository?​