From 724635bbbd7c31a262f5c7b6cc1e8f43907d26c1 Mon Sep 17 00:00:00 2001 From: alexzorin Date: Sat, 4 Feb 2023 06:35:15 +1100 Subject: [PATCH] docs: generate a man page with a structure (#9561) If you looked at [the Debian man page for Certbot](https://manpages.debian.org/bullseye/certbot/certbot.1.en.html) or [the FreeBSD one](https://man.freebsd.org/cgi/man.cgi?query=certbot&sektion=1&apropos=0&manpath=FreeBSD+13.1-RELEASE+and+Ports), you will notice that the entire document is in the "NAME" section. It looks weird in particular on the [FreeBSD man page listing](https://man.freebsd.org/cgi/man.cgi?query=certbot&apropos=1&sektion=0&manpath=FreeBSD+13.1-RELEASE+and+Ports&arch=default&format=html). This PR adds some structure to the man page by adding a new "Synopsis" section (lifted from the Certbot snap's synopsis) and shoving the `certbot --help all` output into a new "Options" section. I think this should be sustainable for us, without having to worry about the man page in particular. Fixes #9560. --- certbot/docs/conf.py | 2 +- certbot/docs/man/certbot.rst | 22 +++++++++++++++++++++- 2 files changed, 22 insertions(+), 2 deletions(-) diff --git a/certbot/docs/conf.py b/certbot/docs/conf.py index de9e287fc..5102e7a1e 100644 --- a/certbot/docs/conf.py +++ b/certbot/docs/conf.py @@ -286,7 +286,7 @@ latex_documents = [ man_pages = [ ('index', 'certbot', u'Certbot Documentation', [project], 7), - ('man/certbot', 'certbot', u'certbot script documentation', + ('man/certbot', 'certbot', u"Automatically configure HTTPS using Let's Encrypt", [project], 1), ] diff --git a/certbot/docs/man/certbot.rst b/certbot/docs/man/certbot.rst index 2f25504b0..cc690d2da 100644 --- a/certbot/docs/man/certbot.rst +++ b/certbot/docs/man/certbot.rst @@ -1,3 +1,23 @@ :orphan: -.. literalinclude:: ../cli-help.txt +======= +certbot +======= + +Synopsis +======== +The objective of Certbot, Let's Encrypt, and the ACME (Automated Certificate Management +Environment) protocol is to make it possible to set up an HTTPS server and have it automatically +obtain a browser-trusted certificate, without any human intervention. This is accomplished by +running a certificate management agent on the web server. + +This agent is used to: + +- Automatically prove to the Let's Encrypt CA that you control the website +- Obtain a browser-trusted certificate and set it up on your web server +- Keep track of when your certificate is going to expire, and renew it +- Help you revoke the certificate if that ever becomes necessary. + +Options +======= +.. literalinclude:: ../cli-help.txt \ No newline at end of file