Skip to content

Single-source documentation where reasonable? #19

@abathur

Description

@abathur

I don't know much about this and a few casual searches haven't turned up many obvious options. It smells like something I'll spin my wheels a lot on.

resholve is largely a solo effort so far, so I'm keeping documentation support fairly modest to avoid meta-work keeping multiple copies/variants in sync, or spinning my wheels on cobbling together a single-sourcing workflow.

Current docs are:

  • The --help flag provides a terse overview of flags and their purpose. (I'm not super happy with ConfigArgParse's default help formatting, and keeping this reference terse mitigates my complaints with it).
  • The manpage (currently hand-written in mdoc) is the only canonical reference.

If you have experience single-sourcing that directly applies or transfers to --help, manpage, README.md, and possibly an external site at some point, help bootstrapping the workflow/toolchain here would be much appreciated.

It's worth discussing the approach before diving in, but I think my main stipulation is that I don't want to single-source in a way that is crappy/suboptimal for all or most of the outputs (i.e., I don't want to just throw the manpage through a few tools to generate plaintext, html, and markdown).

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgood first issueGood for newcomershelp wantedExtra attention is needed

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions