infinitered / orb-publish-docs

CircleCI Orb for publishing docs

Orb Template

Publish Docs Orb

Overview

This orb automates the process of merging Docusaurus documentation from multiple repositories into a single target repository.

What It Does

1. Clone Target Repository: Clones the target Docusaurus documentation repository to the CI environment.
2. Check for Docs: Verifies that documentation files exist in the source repository.
3. Copy Docs: Copies documentation from the source repository to the cloned target repository.
4. Move Static Content: Moves any static content to the appropriate directory in the target repository.
5. Generate category.json: Creates a _category_.json file for new documentation sections.
6. Commit and Push: Commits the changes and pushes them to the target repository.

Features

• Streamlined documentation consolidation
• Configurable paths and labels
• Automatic _category_.json creation

Prerequisites

• CircleCI account
• A Docusaurus documentation repository
• A Machine User with sufficent permissions in both the source and target repos

Note

For the orb to work the CircleCI project must have a User Key with:

• READ permissions for the Source repo
• READ/WRITE permissions for the Target repo

Parameters

Parameter	Type	Description
git_email	String	Email for Git configuration.
git_username	String	Username for Git configuration.
target_repo	String	The GitHub repository URL where the documentation resides.
description	String	Short description of the package used in indexes etc. Default is an empty string.
label	String	The label that will appear in the sidebar of the docs site. Default is "package-name".
project_name	String	The path where these documents will be located on the docs site. Default is an empty string.
source_docs_dir	String	The path to the directory containing the source markdown files. Default is "./docs".

Basic Example

Here's a simple example demonstrating how to use the orb:

version: 2.1

orbs:
  publish-docs: infinitered/publish-docs@x.y.z  # Replace with the actual version
workflows:
    build_docs:
      jobs:
        - publish-docs/build_docs:
            description: "The description that will appear on autogenerated indexes and components."
            git_email: "[e-mail]"
            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: "[e-mail]: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: "[e-mail]"
            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: "[e-mail]:your-org/your-repo.git"
            target_repo_directory: "target" 

Handling Static Files

In your source repository, static files such as images should be placed in a directory named _static_ under your docs folder. The directory structure will look like this when you run the tree command:

docs/
├── part-one.md
├── part-two.md
└── _static_
└── image.png

During the documentation merge process, the orb will automatically move the contents of _static_ to the appropriate location in the target repository.

Directory Structure Before and After Merge

Before Merge:

source-repo/
└── docs/
│ ├── part-one.md
│ └── part-two.md
└── _static_/
    └── image.png

After Merge:

target-repo/
├── docs/
│ └── <<project-name>>
│ ├── part-one.md
│ └── part-two.md
└── static/
    └── <<project-name>>
    └── image.png

By following this convention, you ensure that all static files and documents are correctly placed in the target repository, under docs/<<project-name>> for documents and static/<<project-name>> for static files.

Commands

clone_target

Description

Clones the target documentation repository to ~/target_repo.

Parameters

Parameter	Type	Description
target_repo	String	The GitHub repository URL where the documentation resides.

---

commit_and_push

Description

Commits and pushes the updated documentation to the target repository.

Parameters

None

---

copy_docs_to_target

Description

Clones a Docusaurus repo and adds the docs from the current repo to the target repository.

Parameters

Parameter	Type	Description
description	String	Short description of the package. Default is an empty string.
label	String	The label for the sidebar. Default is "package-name".
project_name	String	The path where the documents will be located on the docs site.
source_docs_dir	String	The path to the directory containing the source markdown files. Default is "./docs".
target_docs_path	String	The path to the directory in the target repo where docs will be copied. Default is "./docs".

---

install_git

Description

Installs Git on the CI environment.

Parameters

None

---

setup_git

Description

Configures Git for commit and push operations.

Parameters

Parameter	Type	Description
git_email	String	Email for Git configuration.
git_username	String	Username for Git configuration.

---

validate_params

Description

Validates that all required parameters are set.

Parameters

Parameter	Type	Description
description	String	Short description of the package.
git_email	String	Email for Git configuration.
git_username	String	Username for Git configuration.
label	String	The label for the sidebar.
project_name	String	The path where the documents will be located on the docs site.
target_repo	String	The GitHub repository URL where the documentation resides.