ansys / ansys/ansys-sphinx-theme

Request for info: Support for persistent multi-level primary sidebar + upgrade-safe customization guidance?

Open
#910 3 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
32
Forks
7
Avg merge
18h 20m
Merged PRs (30d)
36

Description

### Summary:

We're setting up a new Sphinx documentation site ([`cisl-platform`](https://github.com/ansys-internal/cisl-platform) deployment docs) and want a persistent left-hand primary sidebar that provides site-wide navigation up to ~4 levels deep (similar to the Nvidia developer doc model; example: [Omniverse Nucleus](https://docs.omniverse.nvidia.com/nucleus/latest/index.html)).

Before implementing anything, we’d like to confirm whether `ansys-sphinx-theme` supports this out of the box--and if not, learn what the recommended upgrade-safe customization approach is.

### Context:
We aim to keep the site aligned with the broader PyAnsys documentation look-and-feel, so we expect to update Sphinx + `ansys-sphinx-theme` over time.

### Desired behavior:

- Persistent left-hand primary sidebar with navigation visible across the site
- Supports hierarchical navigation up to ~4 levels
- Works with standard Sphinx `toctree` structure
- Guidance on extension points so customization survives theme upgrades

### Questions:

1. Does `ansys-sphinx-theme` support this primary sidebar pattern out of the box, and if so, what’s the recommended configuration?
2. If not, what’s the recommended approach (e.g., documented template override points / theme extension mechanism) to implement it without forking?
3. What’s the best practice for keeping those customizations compatible across new `ansys-sphinx-theme` releases?

If there's additional info that needed, please let me know.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the ansys-sphinx-theme documentation and its support for standard Sphinx toctree navigation, then examine the documented template override points or theme extension mechanism. Done means providing confirmed configuration guidance or a documented upgrade-safe customization path for a persistent, hierarchical primary sidebar.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.