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/.

[leondz]

got it!

[leondz]

fix pushed

[jmartin-tech]

Testing shows this adds a new dependency that should be in docs requirements:

--- a/docs/requirements-docs.txt
+++ b/docs/requirements-docs.txt
@@ -1,3 +1,4 @@
 sphinx
 sphinx-rtd-theme
-sphinx-github-style
\ No newline at end of file
+sphinx-github-style
+sphinx-reredirects

Note also the automation test that ensures new class files have rst doc files needs to be updated as well.

[mikemckiernan]

I'm still neutral on adding directories. imo, no great benefit to humans or machines.

I just haven't been able to give this project the attention it deserves. I attempted using sphinx-autodoc2 for the API section, but it wasn't an improvement. I wanted to explore either generating the API pages automatically--I'm still unsure on that one. The second area for experimentation, is possibly removing pages from the TOC so it's more approachable, and using things like cards and grids on navigation pages for the API to see if that feels better.

Finally, if folks aren't happy with cliref.rst, there's the sphinx-argparse extension to create it from the Python file. iirc, I gave it a shot, but wasn't sure of the appetite for a slight refactor of the code just to produce the docs from the code.

I want to help more, I just haven't been able to get the time.

[leondz]

@mikemckiernan

I'm still neutral on adding directories. imo, no great benefit to humans or machines.

The flat list of hundreds of files was becoming unpleasant to navigate, which prompted the move. Thanks for the reminder to add redirects, though; did that and took the opportunity to add a 404-handler as well, which we didn't have before.

if folks aren't happy with cliref.rst, there's the sphinx-argparse extension to create it from the Python file. iirc, I gave it a shot, but wasn't sure of the appetite for a slight refactor of the code just to produce the docs from the code.

Hadn't seen this, will take a look next time cliref-related churn rears its head!

I wanted to explore either generating the API pages automatically--I'm still unsure on that one. The second area for experimentation, is possibly removing pages from the TOC so it's more approachable, and using things like cards and grids on navigation pages for the API to see if that feels better.

This could be cool. Definitely sounds like a broader project with scope bigger than this PR. I am excited about exploring this, I'm sure we'll work out how & when to slate it eventually.