docs: structure docs out of flat dir into tree

[leondz]

Flat structure isn't working for docs any more. This PR structures them into a tentative dir setup.

• Subdirs for categories having 3+ entries
• File naming removes garak. prefix (they're all about garak)
• category index files prefixed index_

This is a rough structure, feedback welcome

To test:

• make -C docs/source

[jmartin-tech]

Sorry scope creep comment, should we match code structure file name convention, ex: detectors/always.rst instead of detectors/detectors.always.rst?

[leondz]

Very in scope. I thought the same. Landed on this format (type.module) because some plugin modules of different have the same name, so including the type deconflicts the individual filename. On the other hand, the path is enough of a descriptor, and it works fine for the plugins themselves..

Actually, having now said that, maybe it would make sense to mirror the source dir structure??

[jmartin-tech]

I agree matching the source dir structure seems intuitive.

[mikemckiernan]

I was just thinking about you folks a few hours ago!

The downside to directories--unless you cooked up something different--is that typically the directories beg for an index.md file in the directory so that a human at generators/generators.nim.html figures removing the page part of the URL should go to some navigation. An example of that navigation approach is at https://docs.nvidia.com/nemo/microservices/latest/audit/targets/index.html.

Also, you can make the navigation in the TOC more manageable without the directories, in case that was the true goal.

[leondz]

Thanks @mikemckiernan for the tips!

Also, you can make the navigation in the TOC more manageable without the directories,

This wasn't the primary goal but would appreciate input/guidance here, there's room for improvement for sure

[mikemckiernan]

Thanks @mikemckiernan for the tips!

Also, you can make the navigation in the TOC more manageable without the directories,

This wasn't the primary goal but would appreciate input/guidance here, there's room for improvement for sure

Sorry for commenting and then silence for > 24hrs. I just took another look and what's in main is what I meant to recommend:

It requires folks to click to discover content, but the information is available without expanding the TOC enormously.

[mikemckiernan]

Another disadvantage to the directories is consideration for any bookmarked content or current references to these docs. (I'm fairly sure that I made a few.) Please consider using sphinx-reredir if you truly prefer the directories.

[mikemckiernan]

Apologies for the lack of clarity about the index files. I meant to suggest that if you want the directories, that it is kindest to make a docs/source/detectors/index.rst with contents like this, but with revised local paths.

The point is that you'd want something to appear if someone types their way to https://reference.garak.ai/en/latest/detectors/.