ansys / ansys/actions

Support custom documentation path in doc-style and doc-build actions

Open
#1,418 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
19
Forks
7
Avg merge
2d 9h
Merged PRs (30d)
70

Description

## Description

The `doc-style` and `doc-build` actions currently hardcode `doc/` at the repository root in multiple places, making them incompatible with projects that have documentation in a subdirectory (e.g., `blueprint/doc/`, `src/doc/`).

## doc-style

While `vale-config` and `files` inputs are configurable, the vocabulary directory validation step hardcodes `./doc/styles/config/vocabularies`:

```bash
if [ ! -d ./doc/styles/config/vocabularies ]; then
echo "Projects using Vale >=v3 require a doc/styles/config/vocabularies directory."
exit 1
fi
```

### Proposed fix

Use the `files` input (or a new `doc-path` input) to resolve the vocabulary directory path instead of hardcoding `./doc/styles/...`.

## doc-build / _doc-build-linux

Multiple hardcoded `doc/` references in `_doc-build-linux/action.yml`:

- `make -C doc html` / `make -C doc pdf` / `make -C doc linkcheck`
- `EXPECTED_BUILD_DIR=doc/_build`
- `path: doc/_build/html` (artifact upload)
- `path: doc/_build/latex/*.pdf` (artifact upload)

Same issue in `_doc-build-windows/action.yml` with `cd doc`.

### Proposed fix

Add a `doc-path` input (default: `doc`) and use it in place of all hardcoded `doc/` references.

## Current workaround

Projects with non-standard doc paths must create a symlink before calling the actions:

```yaml
- run: ln -s blueprint/doc doc
- uses: ansys/actions/doc-style@v10
with:
checkout: false
vale-config: doc/.vale.ini
files: doc/source
```

This works but is fragile and non-obvious.

Contributor guide

Open the contributing guide

Research direction

Read _doc-build-linux/action.yml and _doc-build-windows/action.yml, then trace how action inputs reach the documented shell commands and artifact paths. Also inspect the doc-style vocabulary validation. Done means a configurable doc-path works on both build actions and the doc-style check no longer assumes ./doc.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions
Domain
ci-cd
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
74/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.