usnistgov/metaschema-xslt

Rewrite the documentation generation standalone XProc

nikitawootten-nist opened this issue · 3 comments

nikitawootten-nist commented

The standalone documentation generation XProc does not currently write outputs correctly. The document should be rewritten to:

  • Re-use (compose) the hugo documentation generation script (which generates fragments without the included CSS or html body pieces)
  • Add an option to override the included CSS with a user-provided stylesheet
  • Name the input/output ports as described in the ADR output of #41
wendellpiez commented

Also: there is WIP XProc now in the repo that could be integrated into this work: a core XProc that runs the entire pipeline while exposing ports, plus a 'wrapper' XProc that exposes no output ports, but instead writes outputs to a designated location.

If this can be emended (a) to capture <div> fragments ready for Hugo, and (b) provide any interfacing for CSS overriding, we will have something that meets the goal of this Issue.

wendellpiez commented

@nikitawootten-nist any chance we could see a link to the place(s) in OSCAL where docs-generation scripting is called? (or: what will the call look like?)

Also note: if we add capabilities vis-a-vis CSS or resource writing we should document those as well. Can we add "update the readme" to the AC for this Issue?

Finally - @aj-stein-nist, the scripts in the repo now (which will be a basis for further work in this Issue), also work to create a standalone docs site for a user's metaschema, with a simple bash script calling maven. This could be tested and demonstrated as-is from #3, and not wait for finer points of Hugo integration.

See https://github.com/wendellpiez/metaschema-xslt/blob/issue2-migration-fixup/src/document/readme.md for more on these scripts and pipelines (kept nearby).