Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Sign up
Appearance settings

chore: simplify the api docs workflow#3186

Open
dougch wants to merge 3 commits into
aws:main from
dougch:api_doc_update
Open

chore: simplify the api docs workflow #3186
dougch wants to merge 3 commits into
aws:main from
dougch:api_doc_update

Conversation

@dougch

@dougch dougch commented Apr 23, 2026
edited
Loading

Copy link
Copy Markdown
Contributor

Issues:

Resolves: none

Description of changes:

The doc.go tool requires being run from the util/ directory with explicit --config and --out flags. This makes the GitHub Pages workflow brittle and the tool unusable from the repo root.

as a reminder, the final doc URL: https://aws.github.io/aws-lc/api/headers.html

Changes:

  • doc.go auto-locates its config file via runtime.Caller(0) — no more CWD dependency
  • Add OutputDirectory field to doc.config so output path lives in config, not the CLI
  • Resolve BaseDirectory and OutputDirectory relative to config file location
  • Auto-create output directory
  • Fix doc.css copy path to be config-relative

Call-outs:

  • This workflow only triggers on push to main, not on PRs — cannot be validated in CI before merge
  • workflow_dispatch can be used to test manually after merge
  • Backwards compatible: --config and --out flags still work as overrides

Testing:

Run locally: go run util/doc.go from repo root — generates docs in pages-output/, with the main entrypoint pages-output/headers.html.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and the ISC license.

codecov-commenter commented Apr 23, 2026
edited
Loading

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.34%. Comparing base (7f7d548) to head (f78a332).

Additional details and impacted files
@@ Coverage Diff @@
## main #3186 +/- ##
==========================================
+ Coverage 78.17% 78.34% +0.17% 
==========================================
 Files 689 689 
 Lines 123732 123735 +3 
 Branches 17199 17204 +5 
==========================================
+ Hits 96723 96941 +218 
+ Misses 26089 25872 -217 
- Partials 920 922 +2 

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@dougch dougch added the documentation Improvements or additions to documentation label Apr 27, 2026
@dougch dougch marked this pull request as ready for review June 8, 2026 22:35
@dougch dougch requested a review from a team as a code owner June 8, 2026 22:35
Comment thread util/doc.go
Comment thread util/doc.go Outdated

@justsmth justsmth left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: Add pages-output/ to .gitignore?

@WillChilds-Klein WillChilds-Klein left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This workflow only triggers on push to main, not on PRs — cannot be validated in CI before merge

what if a malformed comment in a PR causes this to fail? do we have some alarm to know main is broken? can this be caught before merge with a per-PR CI job?

Comment thread util/doc.go
}
}

if err := os.MkdirAll(*outputDir, 0777); err != nil {

@WillChilds-Klein WillChilds-Klein Jun 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do we need to give perms beyond user?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@WillChilds-Klein WillChilds-Klein WillChilds-Klein left review comments

@justsmth justsmth justsmth approved these changes

At least 2 approving reviews are required to merge this pull request.

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

AltStyle によって変換されたページ (->オリジナル) /