UNCLASSIFIED - NO CUI

Spike - Proof-of-concept investigation on mkdocs for static site

Identify tasks required to create a full documentation hosting tool for Big Bang based on mkdocs. The following requirements are should be met:

  • Can build a static site out of source control (Git) so we have a single source of truth and snapshots for each release
  • Can pull source docs from multiple repos and organize them in a meaningful way in the website
  • Source docs are co-located with the software
  • Site can be hosted in cluster in both offline (e.g. airgap) or online mode. This can use a built-in webserver, or a lightweight alternative for hosting the docs.
  • Nice to Have - Using values.yaml to build site with only the enabled application's documents

Spike completion:

  • Demo of subset of Big Bang docs and at least 1 app showing how it meets the above requirements
  • Show static web site in BB cluster hosting apps (can be manually deployed and can turn off other apps/features that may interfere)
  • Identify a breakout of what additional issues may need to be created to fully implement the solution (incl. items like getting containers through Big Bang if we need new ones).
  • Briefly compare/contrast mkdocs with Hugo for situational awareness of team.
Edited by razzle