Incorrect Directory Titles
- Dominant language
- C++
- Stars
- 340
- Forks
- 45
- PR merge metrics
- No merged PRs in 30d
Description
**Describe the bug**
The titles in the front matter for directory pages don't conform to the directories they're being generated from.
**To Reproduce**
Generate yaml for the following files:
- `a/b/h1.hpp`
- `a/c/h2.hpp`
- `a/d/h3.hpp`
The title for the `a` directory page is `a` as expected, but the title for the `a/b` directory page is also `a`. I would expect the title to be `b`.
This does not appear to be a problem if correct documentation already exists. Only when generating it for the first time.
**Expected behavior**
The expectation is that the titles in the directory pages mirror the directories they are generated from.
**Desktop (please complete the following information):**
- OS: MacOS Catalina
- Clang 10.0.0
**Additional context**
After looking into this a little it seems that a recent fix was introduced to write titles when generating the directory stubs, and that that has caused this issue. The `create_directory_stub` defines a static `stub_json_k` variable which always contained just `layout` set to `directory`. A change was introduced to also write the title, but the title is not always the same so the variable should not have remained static.
Making `stub_json_k` no longer static improves the directory naming, but is not sufficient (as far as I can tell) because the title should not always be the `path::filename()` of the directory being created. If the directory name is mangled, then the mangled name is written to the title field. Then, later, during the call to `reconcile` the mangled name already exists and prevents the correct, demangled name from being written to the title field of the merged node.
I have worked around this locally by (a) making `stub_json_k` a local variable in the `create_directory_stub` function, and (b) only writing the title for "true" ancestors. So when creating path directories for `a/b/c`. I only set the title for `a` and `b`, but not for `c`. It seems to work, but I can't really tell whether it's really tackling the core of the problem.
Contributor guide
Research direction
Start by locating create_directory_stub and reconcile, then reproduce the YAML generation with a/b/h1.hpp, a/c/h2.hpp, and a/d/h3.hpp. Trace how directory stub titles are written and merged, including mangled names. Done means generated directory-page front matter uses the matching directory title, including after reconciliation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp, jekyll
- Domain
- documentation, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100