Move man page to section 7

[hynek]

fixes #469

[codecov]

Codecov Report

Base: 100.00% // Head: 100.00% // No change to project coverage 👍

Coverage data is based on head (3d5996b) compared to base (ffcc117).
Patch has no changes to coverable lines.

Additional details and impacted files

@@            Coverage Diff            @@
##             trunk      #470   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           13        13           
  Lines          613       613           
  Branches       143       143           
=========================================
  Hits           613       613           

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[adiroiban]

I don't know if this helps.

From what I can see, we don't build the man pages using Sphinx.

And in this PR, this looks like a Sphinx only change.

---

I don't think that we have any official man page version of the doc.

The plan is to use the click man page generator helper to generate a man page version of the towncrier CLI tool ... so click-man towncrier

Some work here #395

---

So maybe is best to remove the man page info from Sphinx, as that configuration is not used.

[hynek]

My presumption here was that distros use it. If we ever have a replacement, sure let's kill it then.

[bignose-debian]

I don't think that we have any official man page version of the doc.

The existing documentation is suitable, now that it is moved to manual section 7 to describe the Towncrier system as a whole.

There still is not an official manual page for the 'towncrier' command, suitable for manual section 1. You're correct on that.

The plan is to use the click man page generator helper to generate a man page version of the towncrier CLI tool ... so click-man towncrier

I look forward to that being part of the build system.

So maybe is best to remove the man page info from Sphinx, as that configuration is not used.

I don't see a need to remove this? The two manual pages (one in section 7, one in section 1) serve different purposes, both are useful. See the 'man-pages(7)' manual page for more.

[adiroiban]

OK. Makes some sense.

But we don't put any effort into making sure that the Sphinx docs pages are readable as man pages.

I think that if distro want/need a man page, is best to either use click-man to generate the man pages or use a stub page that direct to the webpage.

We now have versioned documentation - https://towncrier.readthedocs.io/en/22.12.0/

So distros can link to older/pin towncrier versions.

[bignose-debian]

But we don't put any effort into making sure that the Sphinx docs pages are readable as man pages.

That's understandable, though disappointing. The Unix manual system is an important part of keeping documentation available in the existing standard system directly on the host, even when offline.

I think that if distro want/need a man page, is best to either use click-man to generate the man pages

I look forward to this being part of the build system for Towncrier.

or use a stub page that direct to the webpage.

That would defeat the purpose, since the Unix manual is intended to be documentation directly on the same host. It should be document the topics covered even when offline.