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; automatically enforce a limit on max depth of sidebar hierarchy #556

Open
1 task
felker opened this issue Dec 3, 2024 · 0 comments
Labels
maintenance Preserving quality source code and tools for docs authors (via GitHub Actions, CLI utilities, etc.) organization where to place/split/replicate .md content; nav menu dropdown and folder hierarchy style subjective design choices, language conventions, how and when to use mkdocs & theme features

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.

@felker felker added style subjective design choices, language conventions, how and when to use mkdocs & theme features organization where to place/split/replicate .md content; nav menu dropdown and folder hierarchy labels Mar 13, 2025
@felker felker changed the title Standardize per-machine hierarchy of sidebar sections/directory names/etc; limit max depth of sidebar hierarchy Standardize per-machine hierarchy of sidebar sections/directory names/etc; automatically enforce a limit on max depth of sidebar hierarchy Mar 14, 2025
@felker felker added the maintenance Preserving quality source code and tools for docs authors (via GitHub Actions, CLI utilities, etc.) label Mar 14, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
maintenance Preserving quality source code and tools for docs authors (via GitHub Actions, CLI utilities, etc.) organization where to place/split/replicate .md content; nav menu dropdown and folder hierarchy style subjective design choices, language conventions, how and when to use mkdocs & theme features
Projects
None yet
Development

No branches or pull requests

1 participant