https://github.com/manics/action-sphinx-linkcheck-summary

https://github.com/manics/action-sphinx-linkcheck-summary

Last synced: 3 months ago
JSON representation

• Host: GitHub
• URL: https://github.com/manics/action-sphinx-linkcheck-summary
• Owner: manics
• Created: 2023-08-05T14:34:30.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2024-08-26T23:12:00.000Z (4 months ago)
• Last Synced: 2024-08-27T01:44:56.805Z (4 months ago)
• Language: Shell
• Size: 6.84 KB
• Stars: 0
• Watchers: 2
• Forks: 0
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md

Awesome Lists containing this project

README

        
# GitHub Action: Run Sphinx linkcheck and summarise results

[![GitHub Action badge](https://github.com/manics/action-sphinx-linkcheck-summary/workflows/Test/badge.svg)](https://github.com/manics/action-sphinx-linkcheck-summary/actions)

## Pre-requisites

The repository must contain a [Sphinx project](https://www.sphinx-doc.org) with a `Makefile` that supports the `linkcheck` target.

For example, you can use the `sphinx-quickstart` utility.

## Optional input parameters

- `docs-dir`: The directory containing the Sphinx documentation.

- `build-dir`: The directory containing the built documentation.

- `sphinx-options`: Sphinx linkchecker options.

- `no-error`: Default is to fail if the linkcheck returns a non-zero exit code, set to `false` to disable. Note this may hide other errors.

## Outputs

- `broken-links-count`: The number of broken links.

- `permanent-redirects-count`: The number of permanent redirects.

## Example

```yaml

name: Example workflow

on:

  pull_request:

  push:

  workflow_dispatch:

jobs:

  test_linkcheck:

    runs-on: ubuntu-22.04

    steps:

      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5

        with:

          python-version: "3.11"

      - run: pip install Sphinx

      - uses: manics/action-sphinx-linkcheck-summary@main

        with:

          docs-dir: docs

          build-dir: docs/_build

```

## Development

You can run the summary script locally:

```sh

./summarise-linkcheck-output.bash docs/_build/linkcheck/output.json

```

where `docs/_build/linkcheck/output.json` is the output of the Sphinx linkchecker.