> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# infinitered/publish-docs

An orb to merge docusaurus docs from several repos. Copies the docs from the current repo to the target repo, then builds the docs to make sure they're working.


## Commands

### build_docusaurus

Runs the Docusaurus build script to ensure that the documentation builds without errors.

### clone_required_repos

"Setup git and clone required repositories"


### clone_required_repos_and_forks

"Setup git and clone required repositories"


### commit_and_push_to_target

"Commits and pushes the updated documentation to the docs repository."


| Parameter | Type | Default | Description |
|---|---|---|---|
| `ssh_key_fingerprint` | string |  | The SSH key fingerprint to use for git push operations |

### copy_docs_to_target

"Clones a docusaurus repo and adds the docs from the current repo to it."


### extract_github_org_and_repo

"Extracts GitHub organization and repository name from the repository URL."


### fetch_commit_info

"Fetch the last commit message and commit hash from the source repository."


### generate_commit_message

"Constructs the final commit message incorporating all relevant details and links."


### install_and_cache_yarn_dependencies

Install Yarn dependencies and cache them.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `repo_directory` | string | ./ | The directory for repository operations. |

### normalize_repository_url

"Normalizes the GitHub URL for use in later parts of the script."


### validate_param

"Validate that a parameter has been defined"


| Parameter | Type | Default | Description |
|---|---|---|---|
| `param_name` | string |  | The name of the parameter to validate and store. |
| `param_value` | string |  | The value of the parameter to validate and store. |

### validate_params

"Validate that all required parameters are set"


| Parameter | Type | Default | Description |
|---|---|---|---|
| `description` | string |  | Short description of the package used in indexes etc. |
| `git_email` | string |  | Email for Git configuration. |
| `git_username` | string |  | Username for Git configuration. |
| `label` | string |  | The label that will appear in the sidebar of the docs site. |
| `project_name` | string |  | The path where these documents will be located on the docs site. |
| `target_repo` | string |  | The GitHub repository URL where the documentation resides. |

## Jobs

### build_docs

Test the documentation without pushing changes.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `description` | string |  | The description of the category that this documentation where these docs will live in the sidebar. |
| `git_email` | string |  | The Git email for commit and push operations. |
| `git_username` | string |  | The Git username for commit and push operations. |
| `label` | string |  | The label for this section that will appear in the sidebar. |
| `project_name` | string |  | The name of the package. Defaults to the repository name if empty. |
| `source_docs_dir` | string | docs | The path to the ir-docs folder in the repository. Defaults to './docs'. |
| `source_repo_directory` | string | source | The directory where the clone of the source repo has been cloned. |
| `target_docs_dir` | string | docs | The path to the ir-docs folder in the repository. Defaults to './docs'. |
| `target_repo` | string |  | The GitHub SSH URL of the target repository where the documentation resides. |
| `target_repo_directory` | string | target | The directory where the clone of the target repo will been cloned. |

### build_docs_include_forks

Test the documentation

| Parameter | Type | Default | Description |
|---|---|---|---|
| `confirm_manual_approval_in_place` | string |  | This job will run code from forked repos. Code should always be manually reviewed before this job is run. Pass 'yes' to this parameter to confirm that you've set up an approval step."
 |
| `description` | string |  | The description of the category that this documentation where these docs will live in the sidebar. |
| `git_email` | string |  | The Git email for commit and push operations. |
| `git_username` | string |  | The Git username for commit and push operations. |
| `label` | string |  | The label for this section that will appear in the sidebar. |
| `project_name` | string |  | The name of the package. Defaults to the repository name if empty. |
| `source_docs_dir` | string | docs | The path to the ir-docs folder in the repository. Defaults to './docs'. |
| `source_repo_directory` | string | source | The directory where the clone of the source repo has been cloned. |
| `target_docs_dir` | string | docs | The path to the ir-docs folder in the repository. Defaults to './docs'. |
| `target_repo` | string |  | The GitHub SSH URL of the target repository where the documentation resides. |
| `target_repo_directory` | string | target | The directory where the clone of the target repo will been cloned. |

### publish_docs

The main job that orchestrates the documentation update process.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `description` | string |  | The description of the category that this documentation where these docs will live in the sidebar. |
| `git_email` | string |  | The Git email for commit and push operations. |
| `git_username` | string |  | The Git username for commit and push operations. |
| `label` | string |  | The label for this section that will appear in the sidebar. |
| `project_name` | string |  | The name of the package. Defaults to the repository name if empty. |
| `source_docs_dir` | string | docs | The path to the ir-docs folder in the repository. Defaults to './docs'. |
| `source_repo_directory` | string | source | The directory where the clone of the source repo has been cloned. |
| `ssh_key_fingerprint` | string |  | The fingerprint of the SSH key to use for pushing to the target repository. |
| `target_docs_dir` | string | docs | The path to the ir-docs folder in the repository. Defaults to './docs'. |
| `target_repo` | string |  | The GitHub SSH URL of the target repository where the documentation resides. |
| `target_repo_directory` | string | target | The directory where the clone of the target repo will been cloned. |

## Examples

### basic_usage

Basic usage of the publish-docs orb.


```yaml
version: '2.1'
orbs:
  publish-docs: infinitered/publish-docs@x.y.z
workflows:
  build_docs:
    jobs:
      - publish-docs/build_docs:
          description: >-
            The description that will appear on autogenerated indexes and
            components.
          git_email: your.ci@email.here
          git_username: Your CI Username
          label: The label that will appear in the sidebar of the docs site.
          project_name: name-of-project
          source_docs_dir: docs
          source_repo_directory: source
          target_docs_dir: docs
          target_repo: git@github.com:your-org/your-repo.git
          target_repo_directory: target
  publish_to_docs_site:
    jobs:
      - publish-docs/publish_docs:
          description: >-
            The description that will appear on autogenerated indexes and
            components.
          git_email: your.ci@email.here
          git_username: Your CI Username
          label: The label that will appear in the sidebar of the docs site.
          project_name: name-of-project
          source_docs_dir: docs
          source_repo_directory: source
          target_docs_dir: docs
          target_repo: git@github.com:your-org/your-repo.git
          target_repo_directory: target
```