From 64fa2432a15c32f135efdf9506d9ce836e55304c Mon Sep 17 00:00:00 2001 From: mtkennerly Date: Thu, 25 Jul 2024 23:12:13 -0400 Subject: [PATCH] Add manpage --- docs/dunamai.1 | 751 ++++++++++++++++++++++++++++++++++++++++++++ dunamai/__main__.py | 6 +- poetry.lock | 18 +- pyproject.toml | 1 + tasks.py | 42 +++ 5 files changed, 816 insertions(+), 2 deletions(-) create mode 100644 docs/dunamai.1 diff --git a/docs/dunamai.1 b/docs/dunamai.1 new file mode 100644 index 0000000..3d71095 --- /dev/null +++ b/docs/dunamai.1 @@ -0,0 +1,751 @@ +.TH DUNAMAI "1" "2024\-07\-26" "dunamai 1.21.2" "Dunamai" +.SH NAME +dunamai +.SH SYNOPSIS +.B dunamai +[-h] {from,check} ... +.SH DESCRIPTION +Generate dynamic versions + +.SH +POSITIONAL ARGUMENTS +.SS \fBdunamai from\fR +Generate version from a particular VCS + +usage: dunamai from [\-h] + {any,git,mercurial,darcs,subversion,bazaar,fossil,pijul} + ... + +Generate version from a particular VCS + +.SS \fBdunamai from any\fR +Generate version from any detected VCS + +usage: dunamai from any [\-h] [\-\-metadata] [\-\-no\-metadata] [\-\-dirty] + [\-\-ignore\-untracked] [\-\-tagged\-metadata] + [\-\-pattern PATTERN] [\-\-pattern\-prefix PATTERN_PREFIX] + [\-\-format FORMAT] [\-\-style {pep440,semver,pvp}] + [\-\-latest\-tag] [\-\-strict] [\-\-path PATH] [\-\-debug] + [\-\-bump] [\-\-full\-commit] [\-\-tag\-branch TAG_BRANCH] + [\-\-tag\-dir TAG_DIR] + +Generate version from any detected VCS + +options: +.RS 7 +.TP +\fB\-\-metadata\fR +Always include metadata. Ignored when \-\-format is used + +.TP +\fB\-\-no\-metadata\fR +Never include metadata. Ignored when \-\-format is used + +.TP +\fB\-\-dirty\fR +Include dirty flag if applicable. Ignored when \-\-format is used + +.TP +\fB\-\-ignore\-untracked\fR +Ignore untracked files when determining whether the repository is dirty (only: +Git) + +.TP +\fB\-\-tagged\-metadata\fR +Include tagged metadata if applicable. Ignored when \-\-format is used + +.TP +\fB\-\-pattern\fR \fI\,PATTERN\/\fR +Regular expression matched against the version source. This must contain one +capture group named `base` corresponding to the release segment of the source. +Optionally, it may contain another two groups named `stage` and `revision` +corresponding to a prerelease type (such as 'alpha' or 'rc') and number (such +as in 'alpha\-2' or 'rc3'). It may also contain a group named `tagged_metadata` +corresponding to extra metadata after the main part of the version (typically +after a plus sign). There may also be a group named `epoch` for the PEP 440 +concept. If the `base` group is not present, then instead this will be +interpreted as a named preset, which may be one of the following: `default`, +`default\-unprefixed` + +.TP +\fB\-\-pattern\-prefix\fR \fI\,PATTERN_PREFIX\/\fR +Insert this after the pattern's start anchor (`^`). + +.TP +\fB\-\-format\fR \fI\,FORMAT\/\fR +Custom output format. Available substitutions: {base}, {stage}, {revision}, +{distance}, {commit}, {dirty}, {tagged_metadata}, {epoch}, {branch}, +{branch_escaped}, {timestamp} + +.TP +\fB\-\-style\fR \fI\,{pep440,semver,pvp}\/\fR +Preconfigured output format. Will default to PEP 440 if not set and no custom +format given. If you specify both a style and a custom format, then the format +will be validated against the style's rules + +.TP +\fB\-\-latest\-tag\fR +Only inspect the latest tag on the latest tagged commit for a pattern match + +.TP +\fB\-\-strict\fR +Elevate warnings to errors. When there are no tags, fail instead of falling +back to 0.0.0 + +.TP +\fB\-\-path\fR \fI\,PATH\/\fR +Directory to inspect, if not the current working directory + +.TP +\fB\-\-debug\fR +Display additional information on stderr for troubleshooting + +.TP +\fB\-\-bump\fR +Increment the last part of the version `base` by 1, unless the `stage` is set, +in which case increment the `revision` by 1 or set it to a default of 2 if +there was no `revision` Does nothing when on a commit with a version tag. + +.TP +\fB\-\-full\-commit\fR +Get the full commit hash instead of the short form (only: Git, Mercurial) + +.TP +\fB\-\-tag\-branch\fR \fI\,TAG_BRANCH\/\fR +Branch on which to find tags, if different than the current branch (only: Git) + +.TP +\fB\-\-tag\-dir\fR \fI\,TAG_DIR\/\fR +Location of tags relative to the root (only: Subversion) +.RE + +.SS \fBdunamai from git\fR +Generate version from Git + +usage: dunamai from git [\-h] [\-\-metadata] [\-\-no\-metadata] [\-\-dirty] + [\-\-ignore\-untracked] [\-\-tagged\-metadata] + [\-\-pattern PATTERN] [\-\-pattern\-prefix PATTERN_PREFIX] + [\-\-format FORMAT] [\-\-style {pep440,semver,pvp}] + [\-\-latest\-tag] [\-\-strict] [\-\-path PATH] [\-\-debug] + [\-\-bump] [\-\-full\-commit] [\-\-tag\-branch TAG_BRANCH] + +Generate version from Git + +options: +.RS 7 +.TP +\fB\-\-metadata\fR +Always include metadata. Ignored when \-\-format is used + +.TP +\fB\-\-no\-metadata\fR +Never include metadata. Ignored when \-\-format is used + +.TP +\fB\-\-dirty\fR +Include dirty flag if applicable. Ignored when \-\-format is used + +.TP +\fB\-\-ignore\-untracked\fR +Ignore untracked files when determining whether the repository is dirty (only: +Git) + +.TP +\fB\-\-tagged\-metadata\fR +Include tagged metadata if applicable. Ignored when \-\-format is used + +.TP +\fB\-\-pattern\fR \fI\,PATTERN\/\fR +Regular expression matched against the version source. This must contain one +capture group named `base` corresponding to the release segment of the source. +Optionally, it may contain another two groups named `stage` and `revision` +corresponding to a prerelease type (such as 'alpha' or 'rc') and number (such +as in 'alpha\-2' or 'rc3'). It may also contain a group named `tagged_metadata` +corresponding to extra metadata after the main part of the version (typically +after a plus sign). There may also be a group named `epoch` for the PEP 440 +concept. If the `base` group is not present, then instead this will be +interpreted as a named preset, which may be one of the following: `default`, +`default\-unprefixed` + +.TP +\fB\-\-pattern\-prefix\fR \fI\,PATTERN_PREFIX\/\fR +Insert this after the pattern's start anchor (`^`). + +.TP +\fB\-\-format\fR \fI\,FORMAT\/\fR +Custom output format. Available substitutions: {base}, {stage}, {revision}, +{distance}, {commit}, {dirty}, {tagged_metadata}, {epoch}, {branch}, +{branch_escaped}, {timestamp} + +.TP +\fB\-\-style\fR \fI\,{pep440,semver,pvp}\/\fR +Preconfigured output format. Will default to PEP 440 if not set and no custom +format given. If you specify both a style and a custom format, then the format +will be validated against the style's rules + +.TP +\fB\-\-latest\-tag\fR +Only inspect the latest tag on the latest tagged commit for a pattern match + +.TP +\fB\-\-strict\fR +Elevate warnings to errors. When there are no tags, fail instead of falling +back to 0.0.0 + +.TP +\fB\-\-path\fR \fI\,PATH\/\fR +Directory to inspect, if not the current working directory + +.TP +\fB\-\-debug\fR +Display additional information on stderr for troubleshooting + +.TP +\fB\-\-bump\fR +Increment the last part of the version `base` by 1, unless the `stage` is set, +in which case increment the `revision` by 1 or set it to a default of 2 if +there was no `revision` Does nothing when on a commit with a version tag. + +.TP +\fB\-\-full\-commit\fR +Get the full commit hash instead of the short form (only: Git, Mercurial) + +.TP +\fB\-\-tag\-branch\fR \fI\,TAG_BRANCH\/\fR +Branch on which to find tags, if different than the current branch (only: Git) +.RE + +.SS \fBdunamai from mercurial\fR +Generate version from Mercurial + +usage: dunamai from mercurial [\-h] [\-\-metadata] [\-\-no\-metadata] [\-\-dirty] + [\-\-tagged\-metadata] [\-\-pattern PATTERN] + [\-\-pattern\-prefix PATTERN_PREFIX] + [\-\-format FORMAT] [\-\-style {pep440,semver,pvp}] + [\-\-latest\-tag] [\-\-strict] [\-\-path PATH] + [\-\-debug] [\-\-bump] [\-\-full\-commit] + +Generate version from Mercurial + +options: +.RS 7 +.TP +\fB\-\-metadata\fR +Always include metadata. Ignored when \-\-format is used + +.TP +\fB\-\-no\-metadata\fR +Never include metadata. Ignored when \-\-format is used + +.TP +\fB\-\-dirty\fR +Include dirty flag if applicable. Ignored when \-\-format is used + +.TP +\fB\-\-tagged\-metadata\fR +Include tagged metadata if applicable. Ignored when \-\-format is used + +.TP +\fB\-\-pattern\fR \fI\,PATTERN\/\fR +Regular expression matched against the version source. This must contain one +capture group named `base` corresponding to the release segment of the source. +Optionally, it may contain another two groups named `stage` and `revision` +corresponding to a prerelease type (such as 'alpha' or 'rc') and number (such +as in 'alpha\-2' or 'rc3'). It may also contain a group named `tagged_metadata` +corresponding to extra metadata after the main part of the version (typically +after a plus sign). There may also be a group named `epoch` for the PEP 440 +concept. If the `base` group is not present, then instead this will be +interpreted as a named preset, which may be one of the following: `default`, +`default\-unprefixed` + +.TP +\fB\-\-pattern\-prefix\fR \fI\,PATTERN_PREFIX\/\fR +Insert this after the pattern's start anchor (`^`). + +.TP +\fB\-\-format\fR \fI\,FORMAT\/\fR +Custom output format. Available substitutions: {base}, {stage}, {revision}, +{distance}, {commit}, {dirty}, {tagged_metadata}, {epoch}, {branch}, +{branch_escaped}, {timestamp} + +.TP +\fB\-\-style\fR \fI\,{pep440,semver,pvp}\/\fR +Preconfigured output format. Will default to PEP 440 if not set and no custom +format given. If you specify both a style and a custom format, then the format +will be validated against the style's rules + +.TP +\fB\-\-latest\-tag\fR +Only inspect the latest tag on the latest tagged commit for a pattern match + +.TP +\fB\-\-strict\fR +Elevate warnings to errors. When there are no tags, fail instead of falling +back to 0.0.0 + +.TP +\fB\-\-path\fR \fI\,PATH\/\fR +Directory to inspect, if not the current working directory + +.TP +\fB\-\-debug\fR +Display additional information on stderr for troubleshooting + +.TP +\fB\-\-bump\fR +Increment the last part of the version `base` by 1, unless the `stage` is set, +in which case increment the `revision` by 1 or set it to a default of 2 if +there was no `revision` Does nothing when on a commit with a version tag. + +.TP +\fB\-\-full\-commit\fR +Get the full commit hash instead of the short form (only: Git, Mercurial) +.RE + +.SS \fBdunamai from darcs\fR +Generate version from Darcs + +usage: dunamai from darcs [\-h] [\-\-metadata] [\-\-no\-metadata] [\-\-dirty] + [\-\-tagged\-metadata] [\-\-pattern PATTERN] + [\-\-pattern\-prefix PATTERN_PREFIX] [\-\-format FORMAT] + [\-\-style {pep440,semver,pvp}] [\-\-latest\-tag] + [\-\-strict] [\-\-path PATH] [\-\-debug] [\-\-bump] + +Generate version from Darcs + +options: +.RS 7 +.TP +\fB\-\-metadata\fR +Always include metadata. Ignored when \-\-format is used + +.TP +\fB\-\-no\-metadata\fR +Never include metadata. Ignored when \-\-format is used + +.TP +\fB\-\-dirty\fR +Include dirty flag if applicable. Ignored when \-\-format is used + +.TP +\fB\-\-tagged\-metadata\fR +Include tagged metadata if applicable. Ignored when \-\-format is used + +.TP +\fB\-\-pattern\fR \fI\,PATTERN\/\fR +Regular expression matched against the version source. This must contain one +capture group named `base` corresponding to the release segment of the source. +Optionally, it may contain another two groups named `stage` and `revision` +corresponding to a prerelease type (such as 'alpha' or 'rc') and number (such +as in 'alpha\-2' or 'rc3'). It may also contain a group named `tagged_metadata` +corresponding to extra metadata after the main part of the version (typically +after a plus sign). There may also be a group named `epoch` for the PEP 440 +concept. If the `base` group is not present, then instead this will be +interpreted as a named preset, which may be one of the following: `default`, +`default\-unprefixed` + +.TP +\fB\-\-pattern\-prefix\fR \fI\,PATTERN_PREFIX\/\fR +Insert this after the pattern's start anchor (`^`). + +.TP +\fB\-\-format\fR \fI\,FORMAT\/\fR +Custom output format. Available substitutions: {base}, {stage}, {revision}, +{distance}, {commit}, {dirty}, {tagged_metadata}, {epoch}, {branch}, +{branch_escaped}, {timestamp} + +.TP +\fB\-\-style\fR \fI\,{pep440,semver,pvp}\/\fR +Preconfigured output format. Will default to PEP 440 if not set and no custom +format given. If you specify both a style and a custom format, then the format +will be validated against the style's rules + +.TP +\fB\-\-latest\-tag\fR +Only inspect the latest tag on the latest tagged commit for a pattern match + +.TP +\fB\-\-strict\fR +Elevate warnings to errors. When there are no tags, fail instead of falling +back to 0.0.0 + +.TP +\fB\-\-path\fR \fI\,PATH\/\fR +Directory to inspect, if not the current working directory + +.TP +\fB\-\-debug\fR +Display additional information on stderr for troubleshooting + +.TP +\fB\-\-bump\fR +Increment the last part of the version `base` by 1, unless the `stage` is set, +in which case increment the `revision` by 1 or set it to a default of 2 if +there was no `revision` Does nothing when on a commit with a version tag. +.RE + +.SS \fBdunamai from subversion\fR +Generate version from Subversion + +usage: dunamai from subversion [\-h] [\-\-metadata] [\-\-no\-metadata] [\-\-dirty] + [\-\-tagged\-metadata] [\-\-pattern PATTERN] + [\-\-pattern\-prefix PATTERN_PREFIX] + [\-\-format FORMAT] [\-\-style {pep440,semver,pvp}] + [\-\-latest\-tag] [\-\-strict] [\-\-path PATH] + [\-\-debug] [\-\-bump] [\-\-tag\-dir TAG_DIR] + +Generate version from Subversion + +options: +.RS 7 +.TP +\fB\-\-metadata\fR +Always include metadata. Ignored when \-\-format is used + +.TP +\fB\-\-no\-metadata\fR +Never include metadata. Ignored when \-\-format is used + +.TP +\fB\-\-dirty\fR +Include dirty flag if applicable. Ignored when \-\-format is used + +.TP +\fB\-\-tagged\-metadata\fR +Include tagged metadata if applicable. Ignored when \-\-format is used + +.TP +\fB\-\-pattern\fR \fI\,PATTERN\/\fR +Regular expression matched against the version source. This must contain one +capture group named `base` corresponding to the release segment of the source. +Optionally, it may contain another two groups named `stage` and `revision` +corresponding to a prerelease type (such as 'alpha' or 'rc') and number (such +as in 'alpha\-2' or 'rc3'). It may also contain a group named `tagged_metadata` +corresponding to extra metadata after the main part of the version (typically +after a plus sign). There may also be a group named `epoch` for the PEP 440 +concept. If the `base` group is not present, then instead this will be +interpreted as a named preset, which may be one of the following: `default`, +`default\-unprefixed` + +.TP +\fB\-\-pattern\-prefix\fR \fI\,PATTERN_PREFIX\/\fR +Insert this after the pattern's start anchor (`^`). + +.TP +\fB\-\-format\fR \fI\,FORMAT\/\fR +Custom output format. Available substitutions: {base}, {stage}, {revision}, +{distance}, {commit}, {dirty}, {tagged_metadata}, {epoch}, {branch}, +{branch_escaped}, {timestamp} + +.TP +\fB\-\-style\fR \fI\,{pep440,semver,pvp}\/\fR +Preconfigured output format. Will default to PEP 440 if not set and no custom +format given. If you specify both a style and a custom format, then the format +will be validated against the style's rules + +.TP +\fB\-\-latest\-tag\fR +Only inspect the latest tag on the latest tagged commit for a pattern match + +.TP +\fB\-\-strict\fR +Elevate warnings to errors. When there are no tags, fail instead of falling +back to 0.0.0 + +.TP +\fB\-\-path\fR \fI\,PATH\/\fR +Directory to inspect, if not the current working directory + +.TP +\fB\-\-debug\fR +Display additional information on stderr for troubleshooting + +.TP +\fB\-\-bump\fR +Increment the last part of the version `base` by 1, unless the `stage` is set, +in which case increment the `revision` by 1 or set it to a default of 2 if +there was no `revision` Does nothing when on a commit with a version tag. + +.TP +\fB\-\-tag\-dir\fR \fI\,TAG_DIR\/\fR +Location of tags relative to the root (only: Subversion) +.RE + +.SS \fBdunamai from bazaar\fR +Generate version from Bazaar + +usage: dunamai from bazaar [\-h] [\-\-metadata] [\-\-no\-metadata] [\-\-dirty] + [\-\-tagged\-metadata] [\-\-pattern PATTERN] + [\-\-pattern\-prefix PATTERN_PREFIX] [\-\-format FORMAT] + [\-\-style {pep440,semver,pvp}] [\-\-latest\-tag] + [\-\-strict] [\-\-path PATH] [\-\-debug] [\-\-bump] + +Generate version from Bazaar + +options: +.RS 7 +.TP +\fB\-\-metadata\fR +Always include metadata. Ignored when \-\-format is used + +.TP +\fB\-\-no\-metadata\fR +Never include metadata. Ignored when \-\-format is used + +.TP +\fB\-\-dirty\fR +Include dirty flag if applicable. Ignored when \-\-format is used + +.TP +\fB\-\-tagged\-metadata\fR +Include tagged metadata if applicable. Ignored when \-\-format is used + +.TP +\fB\-\-pattern\fR \fI\,PATTERN\/\fR +Regular expression matched against the version source. This must contain one +capture group named `base` corresponding to the release segment of the source. +Optionally, it may contain another two groups named `stage` and `revision` +corresponding to a prerelease type (such as 'alpha' or 'rc') and number (such +as in 'alpha\-2' or 'rc3'). It may also contain a group named `tagged_metadata` +corresponding to extra metadata after the main part of the version (typically +after a plus sign). There may also be a group named `epoch` for the PEP 440 +concept. If the `base` group is not present, then instead this will be +interpreted as a named preset, which may be one of the following: `default`, +`default\-unprefixed` + +.TP +\fB\-\-pattern\-prefix\fR \fI\,PATTERN_PREFIX\/\fR +Insert this after the pattern's start anchor (`^`). + +.TP +\fB\-\-format\fR \fI\,FORMAT\/\fR +Custom output format. Available substitutions: {base}, {stage}, {revision}, +{distance}, {commit}, {dirty}, {tagged_metadata}, {epoch}, {branch}, +{branch_escaped}, {timestamp} + +.TP +\fB\-\-style\fR \fI\,{pep440,semver,pvp}\/\fR +Preconfigured output format. Will default to PEP 440 if not set and no custom +format given. If you specify both a style and a custom format, then the format +will be validated against the style's rules + +.TP +\fB\-\-latest\-tag\fR +Only inspect the latest tag on the latest tagged commit for a pattern match + +.TP +\fB\-\-strict\fR +Elevate warnings to errors. When there are no tags, fail instead of falling +back to 0.0.0 + +.TP +\fB\-\-path\fR \fI\,PATH\/\fR +Directory to inspect, if not the current working directory + +.TP +\fB\-\-debug\fR +Display additional information on stderr for troubleshooting + +.TP +\fB\-\-bump\fR +Increment the last part of the version `base` by 1, unless the `stage` is set, +in which case increment the `revision` by 1 or set it to a default of 2 if +there was no `revision` Does nothing when on a commit with a version tag. +.RE + +.SS \fBdunamai from fossil\fR +Generate version from Fossil + +usage: dunamai from fossil [\-h] [\-\-metadata] [\-\-no\-metadata] [\-\-dirty] + [\-\-tagged\-metadata] [\-\-pattern PATTERN] + [\-\-pattern\-prefix PATTERN_PREFIX] [\-\-format FORMAT] + [\-\-style {pep440,semver,pvp}] [\-\-latest\-tag] + [\-\-strict] [\-\-path PATH] [\-\-debug] [\-\-bump] + +Generate version from Fossil + +options: +.RS 7 +.TP +\fB\-\-metadata\fR +Always include metadata. Ignored when \-\-format is used + +.TP +\fB\-\-no\-metadata\fR +Never include metadata. Ignored when \-\-format is used + +.TP +\fB\-\-dirty\fR +Include dirty flag if applicable. Ignored when \-\-format is used + +.TP +\fB\-\-tagged\-metadata\fR +Include tagged metadata if applicable. Ignored when \-\-format is used + +.TP +\fB\-\-pattern\fR \fI\,PATTERN\/\fR +Regular expression matched against the version source. This must contain one +capture group named `base` corresponding to the release segment of the source. +Optionally, it may contain another two groups named `stage` and `revision` +corresponding to a prerelease type (such as 'alpha' or 'rc') and number (such +as in 'alpha\-2' or 'rc3'). It may also contain a group named `tagged_metadata` +corresponding to extra metadata after the main part of the version (typically +after a plus sign). There may also be a group named `epoch` for the PEP 440 +concept. If the `base` group is not present, then instead this will be +interpreted as a named preset, which may be one of the following: `default`, +`default\-unprefixed` + +.TP +\fB\-\-pattern\-prefix\fR \fI\,PATTERN_PREFIX\/\fR +Insert this after the pattern's start anchor (`^`). + +.TP +\fB\-\-format\fR \fI\,FORMAT\/\fR +Custom output format. Available substitutions: {base}, {stage}, {revision}, +{distance}, {commit}, {dirty}, {tagged_metadata}, {epoch}, {branch}, +{branch_escaped}, {timestamp} + +.TP +\fB\-\-style\fR \fI\,{pep440,semver,pvp}\/\fR +Preconfigured output format. Will default to PEP 440 if not set and no custom +format given. If you specify both a style and a custom format, then the format +will be validated against the style's rules + +.TP +\fB\-\-latest\-tag\fR +Only inspect the latest tag on the latest tagged commit for a pattern match + +.TP +\fB\-\-strict\fR +Elevate warnings to errors. When there are no tags, fail instead of falling +back to 0.0.0 + +.TP +\fB\-\-path\fR \fI\,PATH\/\fR +Directory to inspect, if not the current working directory + +.TP +\fB\-\-debug\fR +Display additional information on stderr for troubleshooting + +.TP +\fB\-\-bump\fR +Increment the last part of the version `base` by 1, unless the `stage` is set, +in which case increment the `revision` by 1 or set it to a default of 2 if +there was no `revision` Does nothing when on a commit with a version tag. +.RE + +.SS \fBdunamai from pijul\fR +Generate version from Pijul + +usage: dunamai from pijul [\-h] [\-\-metadata] [\-\-no\-metadata] [\-\-dirty] + [\-\-tagged\-metadata] [\-\-pattern PATTERN] + [\-\-pattern\-prefix PATTERN_PREFIX] [\-\-format FORMAT] + [\-\-style {pep440,semver,pvp}] [\-\-latest\-tag] + [\-\-strict] [\-\-path PATH] [\-\-debug] [\-\-bump] + +Generate version from Pijul + +options: +.RS 7 +.TP +\fB\-\-metadata\fR +Always include metadata. Ignored when \-\-format is used + +.TP +\fB\-\-no\-metadata\fR +Never include metadata. Ignored when \-\-format is used + +.TP +\fB\-\-dirty\fR +Include dirty flag if applicable. Ignored when \-\-format is used + +.TP +\fB\-\-tagged\-metadata\fR +Include tagged metadata if applicable. Ignored when \-\-format is used + +.TP +\fB\-\-pattern\fR \fI\,PATTERN\/\fR +Regular expression matched against the version source. This must contain one +capture group named `base` corresponding to the release segment of the source. +Optionally, it may contain another two groups named `stage` and `revision` +corresponding to a prerelease type (such as 'alpha' or 'rc') and number (such +as in 'alpha\-2' or 'rc3'). It may also contain a group named `tagged_metadata` +corresponding to extra metadata after the main part of the version (typically +after a plus sign). There may also be a group named `epoch` for the PEP 440 +concept. If the `base` group is not present, then instead this will be +interpreted as a named preset, which may be one of the following: `default`, +`default\-unprefixed` + +.TP +\fB\-\-pattern\-prefix\fR \fI\,PATTERN_PREFIX\/\fR +Insert this after the pattern's start anchor (`^`). + +.TP +\fB\-\-format\fR \fI\,FORMAT\/\fR +Custom output format. Available substitutions: {base}, {stage}, {revision}, +{distance}, {commit}, {dirty}, {tagged_metadata}, {epoch}, {branch}, +{branch_escaped}, {timestamp} + +.TP +\fB\-\-style\fR \fI\,{pep440,semver,pvp}\/\fR +Preconfigured output format. Will default to PEP 440 if not set and no custom +format given. If you specify both a style and a custom format, then the format +will be validated against the style's rules + +.TP +\fB\-\-latest\-tag\fR +Only inspect the latest tag on the latest tagged commit for a pattern match + +.TP +\fB\-\-strict\fR +Elevate warnings to errors. When there are no tags, fail instead of falling +back to 0.0.0 + +.TP +\fB\-\-path\fR \fI\,PATH\/\fR +Directory to inspect, if not the current working directory + +.TP +\fB\-\-debug\fR +Display additional information on stderr for troubleshooting + +.TP +\fB\-\-bump\fR +Increment the last part of the version `base` by 1, unless the `stage` is set, +in which case increment the `revision` by 1 or set it to a default of 2 if +there was no `revision` Does nothing when on a commit with a version tag. +.RE + +.SS \fBdunamai check\fR +Check if a version is valid for a style + +usage: dunamai check [\-h] [\-\-style {pep440,semver,pvp}] [version] + +Check if a version is valid for a style + +arguments: +.RS 7 +.TP +\fBversion\fR +Version to check; may be piped in +.RE + + +options: +.RS 7 +.TP +\fB\-\-style\fR \fI\,{pep440,semver,pvp}\/\fR +Style against which to check +.RE + + +.SH AUTHOR +.nf +'Matthew T. Kennerly (mtkennerly)' +.fi + +.SH DISTRIBUTION +The latest version of dunamai may be downloaded from +.UR https://github.com/mtkennerly/dunamai +.UE diff --git a/dunamai/__main__.py b/dunamai/__main__.py index e664864..19416c0 100644 --- a/dunamai/__main__.py +++ b/dunamai/__main__.py @@ -234,8 +234,12 @@ def build_parser( return parser +def get_parser() -> argparse.ArgumentParser: + return build_parser(cli_spec) + + def parse_args(argv=None) -> argparse.Namespace: - return build_parser(cli_spec).parse_args(argv) + return get_parser().parse_args(argv) def from_stdin(value: Optional[str]) -> Optional[str]: diff --git a/poetry.lock b/poetry.lock index 22cee9f..f5bfd54 100644 --- a/poetry.lock +++ b/poetry.lock @@ -1,5 +1,21 @@ # This file is automatically @generated by Poetry 1.5.1 and should not be changed by hand. +[[package]] +name = "argparse-manpage" +version = "4.6" +description = "Build manual page from python's ArgumentParser object." +optional = false +python-versions = "*" +files = [ + {file = "argparse-manpage-4.6.tar.gz", hash = "sha256:0b659d70fd142876da41c2918bd6de4d027875720b0e4672d6443b51198dbb62"}, +] + +[package.dependencies] +tomli = {version = "*", markers = "python_version < \"3.11\""} + +[package.extras] +setuptools = ["setuptools"] + [[package]] name = "atomicwrites" version = "1.4.1" @@ -823,4 +839,4 @@ testing = ["func-timeout", "jaraco.itertools", "pathlib2", "unittest2"] [metadata] lock-version = "2.0" python-versions = ">=3.5" -content-hash = "6749de6d825b0dc633b558c8bb19883299dbab8c5b488f6665aa5f1098b4edf9" +content-hash = "6aae76ce62dbaab18b9d73df648275266f67fda3151aee9f2b7bda53a1e2379e" diff --git a/pyproject.toml b/pyproject.toml index bdcdf37..dbd4eca 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -38,6 +38,7 @@ pytest-cov = [ black = { version = "22.1.0", python = "^3.7" } mypy = { version = "^0.982", python = "^3.7" } ruff = {version = "^0.0.272", python = "^3.7"} +argparse-manpage = {version = "^4.6", python = ">=3.7"} [tool.poetry.scripts] dunamai = 'dunamai.__main__:main' diff --git a/tasks.py b/tasks.py index 3d87ec6..a809896 100644 --- a/tasks.py +++ b/tasks.py @@ -1,3 +1,4 @@ +import shlex import shutil from pathlib import Path @@ -6,6 +7,14 @@ ROOT = Path(__file__).parent +def get_version() -> str: + for line in (ROOT / "pyproject.toml").read_text("utf-8").splitlines(): + if line.startswith("version ="): + return line.replace("version = ", "").strip('"') + + return "0.0.0" + + @task def install(ctx): ctx.run("pip uninstall -y dunamai") @@ -13,3 +22,36 @@ def install(ctx): ctx.run("poetry build") wheel = next(ROOT.glob("dist/*.whl")) ctx.run('pip install "{}"'.format(wheel)) + + +@task +def docs(ctx): + version = get_version() + manpage = "docs/dunamai.1" + + args = [ + "poetry", + "run", + "argparse-manpage", + "--pyfile", + "dunamai/__main__.py", + "--function", + "get_parser", + "--project-name", + "dunamai", + "--prog", + "dunamai", + "--version", + version, + "--author", + '"Matthew T. Kennerly (mtkennerly)"', + "--url", + "https://github.com/mtkennerly/dunamai", + "--format", + "single-commands-section", + "--output", + manpage, + "--manual-title", + "Dunamai", + ] + ctx.run(shlex.join(args))