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

Named error for files in the wrong folder. E.g., a file with doc_type: "resourcePageType" in the api folder, not the resources folder. #2219

Open
mnorman-ms opened this issue Oct 17, 2024 · 0 comments

Comments

@mnorman-ms
Copy link

Is your feature request related to a problem? Please describe.
Contributors will sometimes misplace topics. For example, they'll place a resourcePageType topic in the api folder, rather than the resources folder. This breaks links, and API Doctor reports the broken links but omits the root cause, which is the misplaced file.

Describe the solution you'd like
I would like API Doctor to produce a named error for this condition. (All apiPageType topics belong in the /api/ folders, resourcePageType topics belong in /resources/, and so on.) We would want a MisplacedFileError to be reported. This would probably be based on a mapping file, something like:

....
   "typelocations": {
      "apiPageType": ["api-reference/beta/api/", "api-reference/v1.0/api/"],
      "resourcePageType": [..],
      ...

Describe alternatives you've considered
The alternative is to squint at the file like a sun-stroked pirate, never trust any error message, and eventually turn to drink.

Additional context
This presumes there are predictable locations for these things. Overviews tend to pop up everywhere, so maybe the list of locations could contain a "*" value. We would probably have to report an "UnknownPageType" with a file, line number, and column, for "creative" doc_type attribute values, too. (That is, if we don't already do the equivalent.)

It might also be good to report duplicates when one of the files is misplaced. This exact thing happened in the PR that spawned this feature request. The resource topic was added both in the correct location and in the /api/ folder.

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