Doc/fix more warnings

[Thomas A Caswell (tacaswell)]

This fixes some docs warnings in a cleaner way and sets up CI for both the docs build and the tests.

[Copilot]

🟡 Changes recommended

Fix the CI trigger condition and narrow the Sphinx fallback before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This pull request fixes Sphinx documentation warnings and adds CI jobs for tests and documentation builds.

Changes:

• Preserves and documents refinement type aliases.
• Refines Sphinx cross-reference and warning handling.
• Adds GitHub Actions test and documentation jobs.

File summaries

File	Review
src/powderline/schema.py	Documents RefinementParameter and enables postponed annotations.
docs/known_issues.md	Records the documentation-warning work.
docs/conf.py	Contains a typo and an overly broad cross-reference fallback that should be narrowed.
.github/workflows/ci.yaml	Same-repository pull requests can skip the test job due to the workflow condition.

Review details

Suppressed comments (2)

.github/workflows/ci.yaml:49

• The docs job has the same condition as the test job, so same-repository PRs skip the docs build as well: the only configured push run is for main, while this excludes the PR event. Remove the same-repository exclusion (or trigger pushes for all branches) so internal PRs get the warning-free docs check promised by this workflow.

    if: >-
      github.repository == 'NSLS2/PowderLine' &&
      (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository)

docs/conf.py:100

• The fallback is broader than the type-alias case described in the docstring: every unresolved Python class or obj reference is retried with the generic obj role. A misspelled class reference can therefore resolve to an unrelated function/data object with the same name and suppress the intended nitpicky warning; restrict this to the known RefinementParameter alias (and py:class refs).

    if node.get('refdomain') != 'py' or node.get('reftype') not in {'class', 'obj'}:
        return None
    py_domain = env.get_domain('py')
    return py_domain.resolve_xref(
        env, node['refdoc'], app.builder, 'obj', node['reftarget'], node, contnode

• Files reviewed: 4/4 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Correct the docs CI condition so documentation builds run for internal pull requests.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

Copilot review overview

🔵 Needs a closer look

Restrict the docs/conf.py fallback to known aliases to avoid silently mislinking references.

Review effort: Lite
Findings: None

Resolved since last review (1)

• This condition skips the docs job for every same-repository pull request because…

Previously missed (1)

In code that hasn't changed since last review

Restrict unresolved class reference fallback to known aliases

docs/​conf.py:97

This fallback is broader than the documented type-alias workaround: every unresolved Python class or obj reference is retried as obj. If a genuine class reference is misspelled or an ordinary class name collides with a function/data object, Sphinx can silently produce an incorrect link instead of retaining the nitpicky warning. Restrict the retry to the known RefinementParameter alias (or an explicit alias set).

[Copilot]

Copilot review overview

🟡 Changes recommended

Fix the invalid docs/conf.py hook before approval.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1

Open (1)

• Fix syntax errors preventing conf.py import and docs builds · New

[Copilot]

Copilot review overview

🟡 Changes recommended

docs/conf.py contains syntax errors that prevent documentation builds.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 3 · 1

Open (4)

• Remove stray if causing conf.py syntax error · New
• Close missing parenthesis in resolve_xref call · New
• Fix syntax errors preventing conf.py import and docs builds
• Remove inaccurate broad unresolved-reference retry claim · New

[Copilot]

Copilot review overview

🔵 Needs a closer look

Fix the syntax error in docs/conf.py and correct the inaccurate duplicate documentation entry.

Review effort: Lite
Findings: 1 · 1

Open (2)

• Close missing parenthesis in resolve_xref call
• Remove inaccurate broad unresolved-reference retry claim

Resolved since last review (2)

• Remove stray if causing conf.py syntax error
• Fix syntax errors preventing conf.py import and docs builds

[Copilot]

Copilot review overview

🔵 Needs a closer look

Correct the contradictory hook-scope statement in docs/known_issues.md.

Review effort: Lite
Findings: None

Resolved since last review (2)

• Close missing parenthesis in resolve_xref call
• Remove inaccurate broad unresolved-reference retry claim

[Copilot]

Copilot review overview

🟢 Approval recommended

No unresolved review issues were identified.

Review effort: Lite
Findings: None

[Adam Corrao (AdamCorrao)]

PR approved to merge.