Docs Multiplatform Slice

[ravindk89]

Summary

This is the initial work on creating the per-platform docs slices.

There is considerable work to be done, but the contents below are a working MVP with support for at least two platforms built out already and the beginnings of some semblance of organization to single-sourcing.

ToDo

• [ ] Build out the Deployment instructions for all platforms on MVP1.0 list
• [ ] Scan remaining pages for any per-platform changes that requires conditionals
• [ ] Continue restructuring docs to ensure proper division of materials between personas
• [ ] Clean up Makefile to be all-inclusive of a given platform
• [ ] Improve error handling around imported files

Targeted Platforms

MVP1.0 is:

• Linux
• Windows
• MacOS
• Kubernetes (Generic)

Design choices

There are some quirks to how all this works, so I tried to put together some folder-level structures to help.

A key note is that Sphinx treats folder paths as the URL - so if you have something like /source/linux/<blah>, all the content in linux has that in the URL - which would look odd if you have min.io/docs/linux/linux/<stuff>

Instead, we can use the include directive and the conditional directive to work around it.

• The includes directory now has folders for each platform. We can keep either common-style files for piecemeal includes, or entire stepfiles for full include (e.g. quickstart.rst).
• If a file is pretty distinct between platforms, the best things for build performance is to write that entire procedure for the platform and then include it wholesale into the 'root' document
• For platforms that have different URL schemes, we can use .. cond to change the toctree and exclude file we dont' care about
• We need to modify default-conf.py to ensure the per-platform excludes list includes any such content

Other thoughts

This is a massive body of work. We will miss things, we will have to restructure a bit further, and we will likely miss some stuff. But the resulting structure meets our goals of being cleanly partitioned between each target persona, and we can keep everything in a single repo w/o doing multiple platform branches or sub-repos.