Unified documentation for Infinite Red open source projects.
ir-docs is a single instance of Docusaurus that fetches and builds the /docs
folder from all of the major open source libraries under the infinitered
organization and serves them up under docs.infinite.red/<project>
.
For example, Gluegun's docs live at https://github.com/infinitered/gluegun/tree/master/docs
. When new docs are pushed to master
, Gluegun's Circle CI triggers a build action that then prompts ir-docs to publish those docs at docs.infinite.red/gluegun
.
[!Caution] DO NOT EDIT THE
./docs
DIRECTORY IN THIS REPOSITORY!Edits to documentation for a particular project should be made in that project's repository!
Changes in source repos will be automatically pushed to this repository by the CI/CD process and may destructively overwrite any changes made here.
ir-docs
infinitered/publish-docs
To see how your docs will look on docs.infinite.red
before publishing them, you can preview locally using symlinks:
Clone a copy of the ir-docs
repo to your machine
git clone git@github.com:infinitered/ir-docs.git ~/ir-docs
Use the symlink script to link your projects docs folder into the ir-docs/docs
folder.
yarn symlink add [project_name] [path_to_directory]
For instance to link the ignite docs you might do yarn symlink add ignite-cli ../ignite/docs
.
This will:
./docs/ignite-cli
to ./tmp/symlink/ignite-cli
./docs/ignite-cli
that points to ../ignite/docs
_category.json_
file in ./docs/ignite-cli
with the correct project name [!Note] Remember not to commit any changes to the
./docs
folder manually.
3, Run the docusaurus dev server
cd ~/ir-docs
yarn start
The preview should open automatically at http://localhost:3000
Edit your project's docs in place and the changes should hot reload in the browser!
Restore the original folder You can use the restore script to remove the symlink and restore the original files:
yarn symlink remove [project-name]
ir-docs
To prepare your project for ir-docs
you'll need to do the following:
./docs
../reference/filesystem.md
rather than the full URL or the basename /reference/*
..circleci/config.yml
file and call either the build or publish job from your
workflow.
user key
to the CircleCI project settings. (Use the CI User Account.)infinitered/publish-docs
The infinitered/publish-docs
orb is used to build and publish documentation for Infinite Red open source projects.
It is available in the CircleCI Orb Registry.
See below for how to configure it on CircleCI. You will have to enable third-party orbs on your organization if you haven't yet. Go to https://app.circleci.com/settings/organization/github/<yourorganization>/security
to do that.
Imagine we have a repository that publishes docs to ir-docs
. That repo is called open-source-sesame
.
open-source-sesame
and opens a PR.main
.v1.2.3
open-source-sesame
sees a tagged commit and runs using the infinitered/publish-docs
orb.open-source-sesame
into ir-docs
commits and pushes a new commit.ir-docs
rebuilds the new docusaurus site with the updated docs and pushes it to the gh-pages
branch.This is a high-level summary. For full, up-to-date information on the orb and its parameters check the orb registry.
Imagine we have a project open-source-sesame
with the following config:
version: '2.1'
orbs:
publish-docs: infinitered/publish-docs@x.y.z
# Docker defaults
defaults: &defaults
docker:
- image: cimg/node:18.16.1
working_directory: /mnt/ramdisk/repo
workflows:
publish_to_docs_site:
jobs:
# This job builds the docs and publishes them to the specified site
- publish-docs/publish_docs:
<<: *defaults
description: >-
An example open source project.
git_email: your.ci@email.here
git_username: Your CI Username
label: Open Source Sesame
project_name: open-source-sesame
source_docs_dir: docs # path from the source project root where docs are kept
source_repo_directory: source # directory where the source repo is cloned
target_docs_dir: docs # path from the target project root where docs are kept
target_repo: git@github.com:infinitered/ir-docs.git # must use SSH
target_repo_directory: ir-docs # directory where the target repo is cloned
# These filters ensure this only runs on commits to the main branch that are tagged with a version
filters:
branches:
only:
- main
tags:
only:
- '*v[0-9]+\.[0-9]+\.[0-9]+'
Checkout both repos
~/source/
.git@github.com:infinitered/ir-docs.git
into ~/ir-docs/
.Copy docs
~/source/docs
.~/source/docs
to ~/ir-docs/ir-docs/open-source-sesame
.~/ir-docs/ir-docs/open-source-sesame/_static_
to ~/ir-docs/static/open-source-sesame
~/ir-docs/ir-docs/open-source-sesame/_category_.json
with information specified above.Build the docs
~/ir-docs/
~/ir-docs/
to check for broken links etc. Commit and push
ir-docs
and static
to git.main
branch of git@github.com:infinitered/ir-docs.git
.To preview your changes while you work:
docs
folder of the ir-docs
repo.yarn start
in the ir-docs
repo.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.
source-repo/
└── docs/
│ ├── part-one.md
│ └── part-two.md
└── _static_/
└── image.png
ir-docs/
├── 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/<
For all of this to work, the circle CI user account needs to have:
ignite
, reactotron
, etc.), ANDir-docs
[!Note] If you see errors related to credentials, it's likely that one of these permissions has expired.
[!Tip]
- If a
pull
fails then it's probably the source repo that needs to be re-authed.- If a
push
fails then it's probablyir-docs
that needs to be re-authed.
Collaborations & Teams
pageManage Access
check that the Circle CI Bot has the correct role:
Read
ir-docs
: Write
ir-docs
repoCollaborations & Teams
pageir-docs
repo[!Note] The source repo may have other CI tasks that require the bot to have a higher level of access. Please verify the requirements before making changes.
[!Tip] At the time of writing, the circleCI bot appears as
Infinite Red CircleCI User
SSH keys -> Add user
key and click the button again