This tries to fixes #384

The idea is that instead of having a separate man file that duplicated the CLI info from the Python script, we should only have the help content in the python script.

From there, we can export it to man or sphinx.

For this PR I am using the help content from #326

Debian and other distrubtion can run click-man towncrier to generate the man content.

click-man has more info for Debian at https://github.com/click-contrib/click-man#debian-packages

The result of this PR

main commnad


$ towncrier --help
Usage: towncrier [OPTIONS] COMMAND [ARGS]...

  Towncrier is a utility to produce useful, summarised news files for your
  project. Rather than reading the Git history as some newer tools to produce
  it, or having one single file which developers all write to, towncrier reads
  "news fragments" which contain information useful to end users.

  Towncrier delivers the news which is convenient to those that hear it, not
  those that write it.

  That is, a “news fragment” (a small file containing just enough information
  to be useful to end users) can be written that summarises what has changed
  from the “developer log” (which may contain complex information about the
  original issue, how it was fixed, who authored the fix, and who reviewed the
  fix). By compiling a collection of these fragments, towncrier can produce a
  digest of the changes which is valuable to those who may wish to use the
  software.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  build*  Build a combined news file from news fragment.
  check   Check for new fragments on a branch.
  create  Create a new news fragment.

build command

$ towncrier build --help
Usage: towncrier build [OPTIONS]

  Build a combined news file from news fragment.

Options:
  --draft             Render the news fragments to standard output. Don't
                      write to files, don't check versions.
  --config FILE_PATH  Pass a custom config file at FILE_PATH. Default:
                      towncrier.toml or pyproject.toml file, if both files
                      exist, the first will take precedence.
  --dir PATH          Build fragment in directory. Default to current
                      directory.
  --name TEXT         Pass a custom project name.
  --version TEXT      Render the news fragments using given version.
  --date TEXT
  --yes               Do not ask for confirmation to remove news fragments.
  --help              Show this message and exit.

check command

$ towncrier check --help
Usage: towncrier check [OPTIONS]

  Check for new fragments on a branch.

Options:
  --compare-with BRANCH  Checks files changed running git diff --name-ony
                         BRANCH... BRANCH is the branch to be compared with.
                         Default to origin/master
  --dir PATH             Check fragment in directory. Default to current
                         directory.
  --config FILE_PATH     Pass a custom config file at FILE_PATH. Default:
                         towncrier.toml or pyproject.toml file, if both files
                         exist, the first will take precedence.
  --help                 Show this message and exit.

create command

$ towncrier create --help
Usage: towncrier create [OPTIONS] FILENAME

  Create a new news fragment.

  Create a new news fragment called FILENAME or pass the full path for a file.
  Towncrier has a few standard types of news fragments, signified by the file
  extension.

  These are:
  * .feature - a new feature
  * .bugfix - a bug fix
  * .doc - a documentation improvement,
  * .removal - a deprecation or removal of public API,
  * .misc - a ticket has been closed, but it is not of interest to users.

Options:
  --dir PATH          Create fragment in directory. Default to current
                      directory.
  --config FILE_PATH  Pass a custom config file at FILE_PATH. Default:
                      towncrier.toml or pyproject.toml file, if both files
                      exist, the first will take precedence.
  --edit / --no-edit  Open an editor for writing the newsfragment content.
  -c, --content TEXT  Sets the content of the new fragment.
  --help              Show this message and exit.

Jul 16 '22 13:07 adiroiban

Codecov Report

Merging #395 (c839a36) into trunk (f7ab085) will increase coverage by 0.00%. The diff coverage is 100.00%.

@@           Coverage Diff           @@
##            trunk     #395   +/-   ##
=======================================
  Coverage   97.85%   97.85%           
=======================================
  Files          22       22           
  Lines        1399     1400    +1     
  Branches      130      130           
=======================================
+ Hits         1369     1370    +1     
  Misses         15       15           
  Partials       15       15

Impacted Files	Coverage Δ
src/towncrier/_shell.py	`100.00% <ø> (ø)`
src/towncrier/_settings/__init__.py	`100.00% <100.00%> (ø)`
src/towncrier/build.py	`96.42% <100.00%> (ø)`
src/towncrier/check.py	`94.11% <100.00%> (ø)`
src/towncrier/create.py	`97.72% <100.00%> (ø)`

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update f7ab085...c839a36. Read the comment docs.

Jul 16 '22 13:07 codecov[bot]

I think that this is ready for review.

Aug 17 '22 09:08 adiroiban

Thanks for the review.

I realized now that the README or the docs don't talk about click or click-man. I see what I can do as a drive-by fix. But if someone is searching GitHub issues for "man" should be able to find the info.

Aug 17 '22 17:08 adiroiban

Use text from debian man pages for CLI help output.

Codecov Report