diff options
| author | Evan Read <eread@gitlab.com> | 2023-11-17 18:06:05 +0300 |
|---|---|---|
| committer | Sarah German <sgerman@gitlab.com> | 2023-11-17 18:06:05 +0300 |
| commit | fc8ea8ee4a1734a2cc7d2408a395dea06e435848 (patch) | |
| tree | db6b876f6bb79c35e84262f902f6ca156315b99c | |
| parent | 175897054a482c2de7556f28ffe64ce3e68486e0 (diff) | |
Add docs for previewing docs in a workspace
| -rw-r--r-- | doc/setup.md | 34 | ||||
| -rw-r--r-- | dockerfiles/gitlab-docs-workspace.Dockerfile | 5 |
2 files changed, 35 insertions, 4 deletions
diff --git a/doc/setup.md b/doc/setup.md index 29366eef..eed6e3f0 100644 --- a/doc/setup.md +++ b/doc/setup.md @@ -2,10 +2,11 @@ You can set up, compile, update, and preview the GitLab Docs site locally. -Alternatively, you can either: +Alternatively, you can use either: -- Use [GitPod](#using-gitpod). -- Use [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/gitlab_docs.md), if you already +- [GitPod](#using-gitpod). +- A [Workspace](#using-a-workspace). +- [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/gitlab_docs.md), if you already have GDK configured. ## Set up GitLab Docs locally @@ -165,6 +166,33 @@ To commit and push changes: 1. Push your changes by selecting the **Synchronize changes** action in the bottom blue toolbar. If Gitpod asks you how you want to synchronize your changes, select **Push and pull**. +## Using a workspace + +[Workspaces](https://docs.gitlab.com/ee/user/workspace/index.html) provide an environment for opening the `gitlab-docs` +project in a running Docker container where you can preview GitLab documentation. + +To open GitLab Docs in a workspace + +1. Go to the `gitlab-docs` project page: <https://gitlab.com/gitlab-org/gitlab-docs>. +1. Next to the **Find file** button, select **Edit**. +1. Select **New workspace**. +1. In the **Select cluster agent** dropdown, select the only option available. +1. Select **Create workspace**. +1. In the **Preview** column, wait for a link to appear and then select the link. + +The workspace opens with a view of the the `gitlab-docs` source code. + +To preview documentation: + +1. From the hamburger menu, select **Terminal** > **New Terminal**. +1. In the terminal window, run `make setup`. +1. (Optional) To make all the GitLab documentation content available, run `bundle exec rake clone_repositories`. +1. Run `make compile`. +1. To load the documentation preview, run `bundle exec nanoc view --host 0.0.0.0`. + +The preview is available at a URL with the following pattern: `https://3000-workspace-<...>.workspaces.gitlab.dev`, +which is based on the URL of the workspace. + ## Troubleshooting ### Dependency errors when running `make view` diff --git a/dockerfiles/gitlab-docs-workspace.Dockerfile b/dockerfiles/gitlab-docs-workspace.Dockerfile index b276dbdf..c9b51a26 100644 --- a/dockerfiles/gitlab-docs-workspace.Dockerfile +++ b/dockerfiles/gitlab-docs-workspace.Dockerfile @@ -34,4 +34,7 @@ USER 5001 # See https://asdf-vm.com/guide/getting-started.html#official-download RUN git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v${ASDF_VERSION} && \ echo ". $HOME/.asdf/asdf.sh" >> $HOME/.bashrc && \ - ASDF_DIR="${HOME}/.asdf" && . "${HOME}"/.asdf/asdf.sh + ASDF_DIR="${HOME}/.asdf" && . "${HOME}"/.asdf/asdf.sh && \ + # Add preview instructions when opening a terminal in a workspace + echo "echo" >> $HOME/.bashrc && \ + echo "echo For information on how to preview documentation, see: \<https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/setup.md\>." >> $HOME/.bashrc |