Introduction

An overview of the solution to create a web site from a GitHub repo’s documentation.

Assumptions

• The source repo has documentation in markdown files

• The source repo was created following our workflow approach and therefore has the necessary subscription id, client id and client secret repo secrets (TF_SUBSCRIPTION_ID, TF_CLIENT_ID, TF_CLIENT_SECRET)

• The documentation can be successfully built locally with the Sphinx tooling. See documentation/how-tos/publish-markdown-with-sphinx in this repo.

• If you want to have a custom domain for your site, you will need to request that separately.
  
  

Site Provisioning

The site is provisioned as an Azure WebApp using our standard Terraform-based approach.

Repo: ets-ses-docs

The Terraform provisions:

• rg-etsdocs-dev-001 Resource Group

• asp-etsdocs-plan App Service Plan

• Multiple web apps within the App Service Plan. For example, for this repo it is app-etsdocs-gdct

Each Web App running in the App Service Plan is:

• SKU: Standard (S1) See Microsoft pricing

• Operating System: Windows

• Runtime Stack: Node 18 LTS

• Publishing Model: Code

• Instance Count: 1

Default domain provisioned is https://app-etsdocs-[appname].azurewebsites.net

Note: An alternate approach is to integrate with GitHub Pages. Unfortunately, pages published on GitHub Pages are public. We cannot have Seagen internal documents on the public web.

Onboarding a Repo

Once a repo can successfully build sphinx documentation locally (see Assumptions above), the steps to onboard it to publish documentation to a web site are:

Terraform

1. Append the name of the site to the Terraform list variable apps for the ets Terraform workspaces. For example, for dev: ets-ses-docs-dev

2. Apply the Terraform by running the deployment workflow. Verify the site is created in Azure (will be empty content for now).

3. Download the publish profile for your web app in the Azure Portal. Note: It’s a different publish profile per environment. If you are only publishing from your main branch, you only need to download the prod web-app profile.

Documentation Deployment

1. Copy the GitHub workflow sphinx.yml from this repo to the workflow directory of the source repo.

2. Modifications to make to the destination sphinx.yml:

• If you are using a documentation directory src/docs, you can skip this step.
  The paths to the docs in the push: trigger need to match the location of the documentation path in the repo. Likewise, the source directory for the sphinx-build command in the build-sphinx step also needs to match the location of the documentation path in the repo. (Hint: find/replace src/docs with whatever the path to your docs is)

• The app-name suffix in the publish-docs step needs to match the name of what was setup in Terraform step 1 above.

• In your repo, navigate to the Settings page. Under “Secrets and variables | Actions”, create an “environment secret” called DOCS_PUBLISHING_PROFILE. This is a per-environment secret. Set it up for at least your prd environment. Copy the contents of the publishing profile as the secret value.
  
  

EXAMPLE

I want to deploy documentation for my app spaceship.

Terraform:

1. I append “spaceship” to the list of variables in Terraform: [“gdct”,”launchpad”,”spaceship”]

2. Run the workflow to create a new web app in Azure called app-etsdocs-spaceship

3. Verify that the site https://app-etsdocs-spaceship.azurewebsites.net is available. Can also look at Azure Portal’s asp-etsdocs-plan App Service Plan.

4. Within the Azure Portal, I download the publishing profile for your newly-deployed web app.

Deployment:

1. Back in my source repo with the documentation, my docs are all under a src/docs directory off the root. I’ve already verified sphinx builds it successfully and it looks great on my local box when I open the generated site content. I copy the sphinx.yml to my .github/workflows directory.

2. In sphinx.yml, I modify the app-name under publish-docs to be app-etsdocs-spaceship to match what is provisioned in Azure.

3. In my repo, I create a new environment secret DOCS_PUBLISHING_PROFILE for my dev environment and another for my prd environment. I paste the contents of the appropriate downloaded publish profile into the secret value and save the secret.

4. I merge sphinx.yml into the development branch and it executes. I verify my content displays correctly on my site.

5. I don’t want to deploy from development in the future, only from merges to main to I update my push: | branches: section accordingly.