GH action to check docs validity during PR creation

[rborsaru-ansys]

📝 Description of the feature

We want to be able to run some automated steps when a new set of documentation is added to DevRelDocs to help us during the PR approval process.
Some examples are:

• if the documentation is in zip format then open the zip and check the validity as per this documentation - https://doc-guidelines.dev.ansysapis.com/docs/migrate-dev-portal/migrate-package/doxygen-package/#preparation-of-the-output
• if the documentation is a OpenAPI example then we want to run a swagger test using this document and check if this is valid or now
• if the documentation is md format we want to run Vale linter against it and make sure it has a introduction/changelog pages.
  This is a good start, but expect more to come.
  A good example of a similar implementation could be found here:
  https://github.com/ansys-internal/developer-documentation-guidelines

Thank you!

💡 Steps for implementing the feature

• create GH Action workflow that triggers from PR creation
• add zip val;idation job
• add OpenAPI check job
• add Vale validation job

🔗 Useful links and references

No response

[AnsMelanie]

@rborsaru-ansys

Add the following validation for all *.md files:

1. Ensure an index.md file exists and contains a level-1 heading (# Introduction).

2. Verify that a changelog.md file is present.

3. Confirm that the first entry in toc.yml is:

   name: Introduction
   href: index.md

4. Confirm that toc.yml includes a level-1 entry for the changelog:

   name: Changelog
   href: changelog.md

---

[AnsMelanie]

@rborsaru-ansys @anspcoinaud

• We have verified that users with a "Write" role, which is the default role for ansys/all-members can view Actions results and details.

[AnsMelanie]

@rborsaru-ansys

Additional Checks:

• Link validation (all docs): Verify that all internal anchors and external URLs in the generated documentation are valid and accessible.
• Language quality (REST APIs): Use Vale to automatically detect typos, grammar issues, and style inconsistencies.
• Completeness (REST APIs): Ensure that every endpoint includes:
  • A meaningful summary
  • A clear description
  • All relevant response codes
  • Examples for requests and responses

[rborsaru-ansys]

@AnsMelanie @anspcoinaud

Added the requested additional checks:

• link validation - using lychee for this. Need to change the DOCS_FOLDER env variable inside workflow to set what folders will be checked for link validation. More information about it can be found here - https://github.com/lycheeverse/lychee

• language quality - added more files to Vale validation

• Rest API completeness - using spectral npm package for this

The resulted changes have been added to main branch using this PR:
https://github.com/ansys-internal/dpng-docfx-c/pull/4
A full report after running this new validations can be checked in this action:
https://github.com/ansys-internal/dpng-docfx-c/actions/runs/17608366121

[AnsMelanie]

@rborsaru-ansys

Feature request: Integrate Agentic AI into workflow for Vale checks

Context
As discussed in our recent meeting, we’d like to enhance our current workflow by integrating an Agentic AI into the documentation validation process. Currently, when Vale runs on Markdown (.md) files, it only flags errors or warnings, requiring manual review and fixes.

Proposal
We want to involve an Agentic AI at this stage to automatically suggest fixes for any issues detected by Vale.

Workflow Overview

1. A contributor opens a Pull Request.
2. Vale runs on the Markdown files and reports warnings/errors.
3. The Agentic AI generates suggested fixes for the issues flagged.
4. The reviewer is prompted to validate/approve these AI-generated fixes.
5. Once the reviewer approves, subsequent checks are run.
6. If all checks pass, the PR proceeds as usual.

Benefits

• Reduces manual effort in fixing common Vale warnings/errors.
• Speeds up review cycles by providing ready-to-approve fixes.
• Keeps final approval with human reviewers to ensure accuracy.

Next Steps / Open Questions

• How should the AI suggestions be surfaced to the reviewer (PR comment, GitHub suggestion, or separate artifact)?
• Should we allow auto-commit of approved AI fixes, or leave them as suggested changes?
• How do we handle edge cases where the AI fix may not align with the project’s style guidelines?

[rborsaru-ansys]

@rborsaru-ansys

Add the following validation for all *.md files:

1. Ensure an index.md file exists and contains a level-1 heading (# Introduction).
2. Verify that a changelog.md file is present.
3. Confirm that the first entry in toc.yml is:
   name: Introduction
   href: index.md
4. Confirm that toc.yml includes a level-1 entry for the changelog:
   name: Changelog
   href: changelog.md

This is also done now. PR can be found here - https://github.com/ansys-internal/dpng-docfx-c/pull/6
And the last action run can be found here - https://github.com/ansys-internal/dpng-docfx-c/actions/runs/17757203894

[rborsaru-ansys]

I have committed the workflow that uses AI to check syntax and gives suggestions as a github patch file. As discussed this is not very useful now and was built only as a POC. However, i leave it here for future as it might be useful in the future.
workflow file is here - https://github.com/ansys-internal/dpng-docfx-c/blob/main/.github/workflows/vale_ai_fixer.yml
action is here - https://github.com/ansys-internal/dpng-docfx-c/actions/workflows/vale_ai_fixer.yml