Skip to content

Remove live preview of documentation from GDK

Evan Read requested to merge eread/remove-live-preview-of-docs-from-gdk into main

What does this merge request do and why?

Because of the amount of processing we do when nanoc runs, bundle exec nanoc live doesn't really provide an instant view or reload of detected changes.

Starting the site in live mode, it can take more than 40 seconds to for documentation to properly appear, while in the meantime the site appears broken until the processing is complete.

The same situation happens with updates to the doc site. Updates to the content do appear quickly, but the site looks broken until all the processing is complete.

This MR removes nanoc live mode from the the GDK commands, causing GDK to only use nanoc view. This means:

  • When starting GDK, there is a delay in seeing anything, but what you see is completely built.
  • When previewing changes to documentation site in GDK, you must gdk restart gitlab-docs to see changes. When complete, what you see is completely build.

How to set up and validate locally

Example below:

  1. Ensure GitLab Docs is enabled by adding the below configuration in gdk.yml:

    gitlab_docs:
      enabled: true
    gitlab_runner:
      enabled: true
    omnibus_gitlab:
      enabled: true
    charts_gitlab:
      enabled: true
    gitlab_operator:
      enabled: true
  2. Run gdk reconfigure to check if regenerating all configuration is successful.

  3. Run gdk start. Follow the GitLab Docs link in the terminal and note that while you can see something fast, it looks broken for a long time.

  4. Run gdk stop.

  5. Check out to this merge request's branch.

  6. Run gdk start. Follow the GitLab Docs link in the terminal and see that it takes time to appear, but appears completely built.

Impacted categories

The following categories relate to this merge request:

Merge request checklist

  • This change is backward compatible. If not, please include steps to communicate to our users.
  • Tests added for new functionality. If not, please raise an issue to follow-up.
  • Documentation added/updated, if needed.
  • Announcement added, if change is notable.
  • gdk doctor test added, if needed.
  • Add the ~highlight label if this MR should be included in the CHANGELOG.md.
Edited by Evan Read

Merge request reports