From 5a1ae8310f4fb9222af06c8b08fbc95b23bec56c Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Thu, 22 Oct 2020 00:28:57 +0200 Subject: [PATCH] Separate "development" and "production" configurations This patch updates the default configuration to match a "development" situation, and introduces build-options to produce a "production" build. By default (dev environment): - Google Analytics / GTM and PollDaddy are disabled - SASS builds non-minified stylesheets (for easier readabililty) - Excludes "enterprise" stubs Building a "production" build locally is still possible by overriding the `JEKYLL_ENV` build-arg; JEKYLL_ENV=production docker-compose up --build Signed-off-by: Sebastiaan van Stijn --- .github/workflows/build-published.yml | 2 +- Dockerfile | 19 +++- _config.yml | 12 +-- _config_authoring.yml | 122 -------------------------- _config_production.yml | 11 +++ _includes/body.html | 2 +- _includes/head.html | 8 +- docker-compose.yml | 14 +++ 8 files changed, 51 insertions(+), 139 deletions(-) delete mode 100644 _config_authoring.yml create mode 100644 _config_production.yml diff --git a/.github/workflows/build-published.yml b/.github/workflows/build-published.yml index 9b0d97f89c..b56a7cff98 100644 --- a/.github/workflows/build-published.yml +++ b/.github/workflows/build-published.yml @@ -17,7 +17,7 @@ jobs: run: docker version && docker info - uses: actions/checkout@v2 - name: build current docs - run: docker build --target=deploy-source --output=./_site . + run: docker build --build-arg JEKYLL_ENV=production --target=deploy-source --output=./_site . - name: upload files to S3 bucket run: aws s3 sync --acl public-read _site s3://docs.docker.com-us-east-1/ --delete env: diff --git a/Dockerfile b/Dockerfile index b6f9ff4302..4b9fb2bd99 100644 --- a/Dockerfile +++ b/Dockerfile @@ -10,6 +10,8 @@ # # When the image is run, it starts Nginx and serves the docs at port 4000 +# Jekyll environment (development/production) +ARG JEKYLL_ENV=development # Engine ARG ENGINE_BRANCH="19.03" @@ -53,9 +55,16 @@ COPY --from=upstream-resources /usr/src/app/md_source/. ./ # substitute the "{site.latest_engine_api_version}" in the title for the latest # API docs, based on the latest_engine_api_version parameter in _config.yml RUN ./_scripts/update-api-toc.sh -RUN jekyll build -d ${TARGET} \ - && find ${TARGET} -type f -name '*.html' | while read i; do sed -i 's#\(]* href="\)https://docs.docker.com/#\1/#g' "$i"; done \ - && sed -i 's#/#https://docs.docker.com/#' "${TARGET}/sitemap.xml" +ARG JEKYLL_ENV +RUN echo "Building docs for ${JEKYLL_ENV} environment" +RUN set -eux; \ + if [ "${JEKYLL_ENV}" = "production" ]; then \ + jekyll build -d ${TARGET} --config _config.yml,_config_production.yml; \ + else \ + jekyll build -d ${TARGET}; \ + fi; \ + find ${TARGET} -type f -name '*.html' | while read i; do sed -i 's#\(]* href="\)https://docs.docker.com/#\1/#g' "$i"; done; \ + sed -i 's#/#https://docs.docker.com/#' "${TARGET}/sitemap.xml"; # This stage only contains the generated files. It can be used to host the @@ -79,4 +88,6 @@ COPY --from=current /usr/share/nginx/html . # Configure NGINX COPY _deploy/nginx/default.conf /etc/nginx/conf.d/default.conf -CMD echo -e "Docker docs are viewable at:\nhttp://0.0.0.0:4000"; exec nginx -g 'daemon off;' +ARG JEKYLL_ENV +ENV JEKYLL_ENV=${JEKYLL_ENV} +CMD echo -e "Docker docs are viewable at:\nhttp://0.0.0.0:4000 (build target: ${JEKYLL_ENV})"; exec nginx -g 'daemon off;' diff --git a/_config.yml b/_config.yml index 35335d7a0b..4a606c2dcf 100644 --- a/_config.yml +++ b/_config.yml @@ -11,13 +11,7 @@ incremental: true permalink: pretty safe: false lsi: false -exclude: ["_scripts", "tests", "apidocs/layouts", "Gemfile", "hooks", "index.html", "404.html"] - -# Google Analytics, etc. -# TODO these should only be set when building for production, or passed as an environment variable when building -google_analytics: GTM-WL2QLG5 -polldaddy_id: 8453675 - +exclude: ["_samples", "_scripts", "404.html", "datacenter", "ee", "index.html"] # Component versions -- address like site.docker_ce_version # You can't have - characters in these for non-YAML reasons @@ -121,5 +115,5 @@ defaults: # # We specify the directory for Jekyll so we can use @imports. sass: - sass_dir: _scss - style: :compressed + sass_dir: _scss + style: expanded diff --git a/_config_authoring.yml b/_config_authoring.yml deleted file mode 100644 index 96b000f15c..0000000000 --- a/_config_authoring.yml +++ /dev/null @@ -1,122 +0,0 @@ -name: Docker Documentation -markdown: kramdown -kramdown: - input: GFM - gfm_quirks: [paragraph_end, no_auto_typographic] - html_to_native: true - hard_wrap: false - syntax_highlighter: rouge - toc_levels: 2..3 -incremental: false -permalink: pretty -safe: false -lsi: false -exclude: ["_scripts", "tests", "apidocs/layouts", "Gemfile", "hooks", "index.html", "404.html"] - -# Component versions -- address like site.docker_ce_version -# You can't have - characters in these for non-YAML reasons - -# TO USE ME: -# jekyll serve --incremental --config _config_authoring.yml - -latest_engine_api_version: "1.40" -docker_ce_version: "19.03" -compose_version: "1.27.4" -compose_file_v3: "3.8" -compose_file_v2: "2.4" -machine_version: "0.16.0" -distribution_version: "2.7" - -collections: - samples: - output: true - -plugins: - - jekyll-redirect-from - - jekyll-relative-links - - jekyll-sitemap - -defaults: - - scope: - path: "" - type: "pages" - values: - layout: docs - toc_min: 2 - toc_max: 3 - tree: true - - # Set the correct edit-URL for upstream resources. We usually don't create a direct - # edit link for these, and instead point to the directory that contains the file. - - scope: - path: engine/api/v1.* - values: - edit_url: "https://github.com/docker/docker/tree/master/docs/api" - - scope: - path: engine/deprecated - values: - edit_url: "https://github.com/docker/cli/tree/master/docs/" - - scope: - path: engine/extend - values: - edit_url: "https://github.com/docker/cli/tree/master/docs/extend" - - scope: - path: engine/reference - values: - edit_url: "https://github.com/docker/cli/tree/master/docs/reference" - - scope: - path: engine/reference/commandline - values: - edit_url: "https://github.com/docker/cli/tree/master/docs/reference/commandline" - - scope: - path: glossary - values: - edit_url: "https://github.com/docker/docker.github.io/blob/master/_data/glossary.yaml" - - scope: - path: notary/reference - values: - edit_url: "https://github.com/theupdateframework/notary/tree/master/docs/reference" - - scope: - path: registry/configuration - values: - edit_url: "https://github.com/docker/distribution/tree/master/docs" - - scope: - path: registry/spec - values: - edit_url: "https://github.com/docker/distribution/tree/master/docs/spec" - - scope: - path: compliance - values: - edit_url: "https://github.com/mirantis/compliance/tree/master/docs/compliance" - - # Hide Enterprise content from sitemap. These directories still contains stubs - # that are needed to redirect old URLs - - scope: - path: "datacenter" - values: - sitemap: false - title: Docker Enterprise moved to Mirantis - - scope: - path: "desktop/enterprise" - values: - sitemap: false - - scope: - path: "ee" - values: - sitemap: false - title: Docker Enterprise moved to Mirantis - - scope: - path: "machine" - values: - sitemap: false - - scope: - path: "samples/library" - values: - sitemap: false - -# Assets -# -# We specify the directory for Jekyll so we can use @imports. -sass: - sass_dir: _scss - style: :compressed diff --git a/_config_production.yml b/_config_production.yml new file mode 100644 index 0000000000..9b95b00f82 --- /dev/null +++ b/_config_production.yml @@ -0,0 +1,11 @@ + +# Include files that are excluded in "development" ("enterprise" stubs) for production +exclude: ["_scripts", "404.html", "index.html"] + +# Google Analytics, etc. +google_analytics: GTM-WL2QLG5 +polldaddy_id: 8453675 + +# Assets +sass: + style: compressed diff --git a/_includes/body.html b/_includes/body.html index 33a9266030..432ac449eb 100644 --- a/_includes/body.html +++ b/_includes/body.html @@ -73,5 +73,5 @@ {% include footer.html %} - {%- include analytics/polldaddy.html -%} + {%- if jekyll.environment == 'production' -%}{%- include analytics/polldaddy.html -%}{%- endif -%} diff --git a/_includes/head.html b/_includes/head.html index 1088440d00..a14d04392c 100644 --- a/_includes/head.html +++ b/_includes/head.html @@ -24,16 +24,20 @@ {%- assign page_description = content | strip_html | strip | truncatewords: 30 -%} {%- endif -%} {%- endif -%} +{%- assign domain_name = 'https://docs.docker.com' -%} +{%- if jekyll.environment == 'development' -%} +{%- assign domain_name = 'https://localhost:4000' -%} +{%- endif -%} {%- if page.sitemap == false or site.GH_ENV == "gh_pages" %} {%- endif %} - {%- if site.google_analytics != '' -%}{%- include analytics/google_analytics.html GOOGLE_ID=site.google_analytics -%}{%- endif -%} + {%- if jekyll.environment == 'production' and site.google_analytics != '' -%}{%- include analytics/google_analytics.html GOOGLE_ID=site.google_analytics -%}{%- endif -%} {{ page.title | default: page_title }} | Docker Documentation - + diff --git a/docker-compose.yml b/docker-compose.yml index 598c5358b8..024a8faad6 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,7 +1,21 @@ version: "3.7" services: docs: + # By default, docker-compose up --build builds docs for a development + # environment (no Google Analytics, omitting some enterprise redirects, + # etc. + # + # To test a "production" build, override the environment using: + # + # JEKYLL_ENV=production docker-compose up --build build: + args: + # FIXME: docker-compose should behave the same as the docker CLI here + # and if `JEKYLL_ENV` is not set in the current environment, ignore + # the --build-arg, and use the default that's defined in the Dockerfile. + # Setting a default here as a workaround. + # - JEKYLL_ENV + - JEKYLL_ENV=${JEKYLL_ENV:-development} context: . image: docs/docstage ports: