Autodesk / Autodesk/moldflow-api

Docs version switcher links resolve incorrectly on GitHub Pages

Open
#73 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
12
Forks
2
Avg merge
2h 31m
Merged PRs (30d)
2

Description

## Summary

The docs version switcher on GitHub Pages is generating/using the wrong links.

Direct version URLs work, for example:
- `https://autodesk.github.io/moldflow-api/v26.0.5/`
- `https://autodesk.github.io/moldflow-api/latest/`

But using the version switcher UI takes you to the wrong location instead of the corresponding page in the selected version.

## Current behavior

The published switcher data at:
- `https://autodesk.github.io/moldflow-api/latest/_static/switcher.json`

currently contains entries like:

```json
{
"version": "v26.0.5",
"url": "../v26.0.5/"
}
```

Those relative URLs appear to be the root cause of the bad navigation in the switcher UI on GitHub Pages.

## Expected behavior

Selecting a version from the switcher should take the user to the same doc page in the selected version when it exists, or fall back to that version's homepage.

For GitHub Pages, the switcher entries should point at the correct version root for the site, e.g.:
- `https://autodesk.github.io/moldflow-api/v26.0.5/`
- `https://autodesk.github.io/moldflow-api/v27.0.0/`

rather than relative paths like `../v26.0.5/`.

## Local code context

The current local checkout shows the switcher URLs are generated here:
- `scripts/generate_switcher.py`

Specifically:
- `scripts/generate_switcher.py:278` -> `"url": f"../{json_version}/"`
- `scripts/generate_switcher.py:290` -> `"url": f"../{tag}/"`

There is also related switcher config here:
- `docs/source/conf.py:70` -> `"json_url": "_static/switcher.json"`

PyData Sphinx Theme's docs say `switcher['json_url']` should be a stable, fully resolved URL, so that may also be worth reviewing as part of the fix.

## Repro

1. Open the published docs on GitHub Pages.
2. Use the version switcher from the UI.
3. Notice the selected version link does not resolve to the correct docs location.
4. Compare that with opening the direct version URL manually, which works.

## Likely fix

Generate version switcher entries using the GitHub Pages site root (or another stable absolute docs base URL) instead of relative `..//` paths, and verify `json_url` is also configured as a stable absolute URL.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.