Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Standardize per-machine hierarchy of sidebar sections/directory names/etc; limit max depth of sidebar hierarchy #556

Open
1 task
felker opened this issue Dec 3, 2024 · 0 comments

Comments

@felker
Copy link
Member

felker commented Dec 3, 2024

{Polaris, Sophia, Aurora, Crux} wont have a complete overlap of documentation pages, but where they do, the directories and navigation sidebar titles should be named identically. Polaris is probably our currently closest superset:

pwd
./docs/polaris
❯ tree -d
.
├── applications-and-libraries
│   ├── applications
│   └── libraries
├── build-tools
├── compiling-and-linking
│   └── files
├── containers
├── data-science
│   ├── applications
│   └── frameworks
├── debugging-tools
├── hardware-overview
│   └── files
├── performance-tools
│   └── Images
├── programming-models
├── visualization
│   ├── images
│   └── scripts
└── workflows
  • automate checking the symmetry in the names?

As seen in #554, renaming a directory after a significant amount of content has been added has the potential to be quite painful. It breaks all the relative links from .md files that are not children of that directory, plus other absolute links like extensions such as Snippets demands:

--8<-- "./docs/polaris/data-science/frameworks/pytorch.md:scalingsetup"

@FilippoSimini also pointed out that the current sidebar has way too many levels:
image

We could limit the max depth to 3 or so. Should probably revisit this after the significant style redesign in #545 is merged. Bolded "section headers" that don't increase the indentation or require clicking a dropdown arrow can help categorize things too.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant