Skip to content

Commit

Permalink
Merge pull request #12005 from rabbitmq/mk-initial-man-page-updates-f…
Browse files Browse the repository at this point in the history
…or-4.0

Initial man page updates for 4.0
  • Loading branch information
michaelklishin authored Aug 14, 2024
2 parents 1cbe373 + 8fa7f3a commit 9f47ca5
Show file tree
Hide file tree
Showing 13 changed files with 156 additions and 28 deletions.
3 changes: 3 additions & 0 deletions deps/rabbit/docs/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
*.html
*.md

58 changes: 45 additions & 13 deletions deps/rabbit/docs/README.md
Original file line number Diff line number Diff line change
@@ -1,31 +1,63 @@
# Manual Pages and Documentation Extras

This directory contains [CLI tool](https://rabbitmq.com/cli.html) man page sources as well as a few documentation extras:
This directory contains [CLI tools](https://rabbitmq.com/docs/cli/) man page sources as well as a few documentation extras:

* An [annotated rabbitmq.conf example](./rabbitmq.conf.example) (see [new style configuration format](https://www.rabbitmq.com/configure.html#config-file-formats))
* An [annotated advanced.config example](./advanced.config.example) (see [The advanced.config file](https://www.rabbitmq.com/configure.html#advanced-config-file))
* An [annotated rabbitmq.conf example](./rabbitmq.conf.example) (see [new style configuration format](https://www.rabbitmq.com/docs/configure#config-file-formats))
* An [annotated advanced.config example](./advanced.config.example) (see [The advanced.config file](https://www.rabbitmq.com/docs/configure#advanced-config-file))
* A [systemd unit file example](./rabbitmq-server.service.example)

Please [see rabbitmq.com](https://rabbitmq.com/documentation.html) for documentation guides.
Please [see rabbitmq.com](https://rabbitmq.com/docs/) for documentation guides.


## Classic Config File Format Example
## man Pages

Feeling nostalgic and looking for the [classic configuration file example](https://github.com/rabbitmq/rabbitmq-server/blob/v3.7.x/docs/rabbitmq.config.example)?
Now that's old school! Keep in mind that classic configuration file **should be considered deprecated**.
Prefer `rabbitmq.conf` (see [new style configuration format](https://www.rabbitmq.com/configure.html#config-file-formats))
with an `advanced.config` to complement it as needed.
### Dependencies

* `man`
* [`tidy5`](https://binaries.html-tidy.org/) (a.k.a. `tidy-html5`)

## man Pages
On macOS, `tidy5` can be installed with Homebrew:

``` shell
brew install tidy-html5
```

and then be found under the `bin` directory of the Homebrew cellar:

``` shell
/opt/homebrew/bin/tidy --help
```

### Source Files

This directory contains man pages that are converted to HTML using `mandoc`:
This directory contains man pages in ntroff, the man page format.

To inspect a local version, use `man`:

``` shell
man docs/rabbitmq-diagnostics.8

man docs/rabbitmq-queues.8
```

To converted all man pages to HTML using `mandoc`:

``` shell
gmake web-manpages
```

gmake web-manpages
The result then must be post-processed and copied to the website repository:

The result is then copied to the [website repository](https://github.com/rabbitmq/rabbitmq-website/tree/live/site/man)
``` shell
# cd deps/rabbit/docs
#
# clear all generated HTML and Markdown files
rm *.html *.md
# export tidy5 path
export TIDY5_BIN=/opt/homebrew/bin/tidy;
# run the post-processing script, in this case it updates the 3.13.x version of the docs
./postprocess_man_html.sh . /path/to/rabbitmq-website.git/versioned_docs/version-3.13/man/
```

### Contributions

Expand Down
92 changes: 92 additions & 0 deletions deps/rabbit/docs/postprocess_man_html.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
#!/bin/sh

set -e

srcdir="$1"
destdir="$2"

tidy_bin=${TIDY5_BIN:-"tidy5"}

for src in "$srcdir"/*.html; do
name=$(basename "$src" .html)
dest="$destdir/$name.md"
echo "src=$src" "dest=$dest" "name=$name"

cat <<EOF > "$dest"
---
title: $name
---
EOF

$tidy_bin -i --wrap 0 \
--asxhtml \
--show-body-only yes \
--drop-empty-elements yes \
--drop-empty-paras yes \
--enclose-block-text yes \
--enclose-text yes "$src" \
| \
awk '
/<h[1-6]/ {
if ($0 ~ /<h1/) {
level = "#";
} else if ($0 ~ /<h2/) {
level = "##";
} else if ($0 ~ /<h2/) {
level = "##";
} else if ($0 ~ /<h3/) {
level = "###";
} else if ($0 ~ /<h4/) {
level = "####";
} else if ($0 ~ /<h5/) {
level = "#####";
} else if ($0 ~ /<h6/) {
level = "######";
}
id = $0;
sub(/.*(id|name)="/, "", id);
sub(/".*/, "", id);
title = $0;
sub(/ *<\/.*/, "", title);
sub(/.*> */, "", title);
print level, title, "{#" id "}";
next;
}
/dt id="/ {
id = $0;
sub(/.*(id|name)="/, "", id);
sub(/".*/, "", id);
line = $0;
sub(/id="[^"]*"/, "", line);
print line;
next;
}
/a class="permalink"/ {
title = $0;
sub(/ *<a [^>]*>/, "", title);
sub(/<\/a>/, "", title);
sub(/<br[^>]*>/, "", title);
gsub(/>\*</, ">\\&ast;<", title);
print level "#", title, "{#" id "}";
next;
}
{
line = $0;
gsub(/{/, "\\&lcub;", line);
gsub(/<li>/, "<li>\n", line);
gsub(/<\/li>/, "\n</li>", line);
gsub(/<\/ul>/, "</ul>\n", line);
gsub(/<br[^>]*>/, "<br\/>", line);
gsub(/<\/div>]/, "<\/div>\n]", line);
gsub(/style="[^"]*"/, "", line);
print line;
next;
}
' > "$dest"
done
6 changes: 3 additions & 3 deletions deps/rabbit/docs/rabbitmq-diagnostics.8
Original file line number Diff line number Diff line change
Expand Up @@ -697,10 +697,10 @@ See
.Cm quorum_status
in
.Xr rabbitmq-queues 8
.It Cm check_if_node_is_mirror_sync_critical
.It Cm check_if_cluster_has_classic_queue_mirroring_policy
.Pp
See
.Cm check_if_node_is_mirror_sync_critical
.Cm check_if_cluster_has_classic_queue_mirroring_policy
in
.Xr rabbitmq-queues 8
.It Cm check_if_node_is_quorum_critical
Expand All @@ -723,4 +723,4 @@ in
.\" ------------------------------------------------------------------
.Sh AUTHOR
.\" ------------------------------------------------------------------
.An The RabbitMQ Team Aq Mt rabbitmq-core@groups.vmware.com
.An The RabbitMQ Team Aq Mt contact-tanzu-data.pdl@broadcom.com
2 changes: 1 addition & 1 deletion deps/rabbit/docs/rabbitmq-echopid.8
Original file line number Diff line number Diff line change
Expand Up @@ -67,4 +67,4 @@ The short-name form of the RabbitMQ node name.
.\" ------------------------------------------------------------------
.Sh AUTHOR
.\" ------------------------------------------------------------------
.An The RabbitMQ Team Aq Mt rabbitmq-core@groups.vmware.com
.An The RabbitMQ Team Aq Mt contact-tanzu-data.pdl@broadcom.com
2 changes: 1 addition & 1 deletion deps/rabbit/docs/rabbitmq-env.conf.5
Original file line number Diff line number Diff line change
Expand Up @@ -84,4 +84,4 @@ file RabbitMQ configuration file location is changed to "/data/services/rabbitmq
.\" ------------------------------------------------------------------
.Sh AUTHOR
.\" ------------------------------------------------------------------
.An The RabbitMQ Team Aq Mt rabbitmq-core@groups.vmware.com
.An The RabbitMQ Team Aq Mt contact-tanzu-data.pdl@broadcom.com
2 changes: 1 addition & 1 deletion deps/rabbit/docs/rabbitmq-plugins.8
Original file line number Diff line number Diff line change
Expand Up @@ -252,4 +252,4 @@ plugin and its dependencies and disables everything else:
.\" ------------------------------------------------------------------
.Sh AUTHOR
.\" ------------------------------------------------------------------
.An The RabbitMQ Team Aq Mt rabbitmq-core@groups.vmware.com
.An The RabbitMQ Team Aq Mt contact-tanzu-data.pdl@broadcom.com
9 changes: 5 additions & 4 deletions deps/rabbit/docs/rabbitmq-queues.8
Original file line number Diff line number Diff line change
Expand Up @@ -182,13 +182,14 @@ This command is currently only supported by quorum queues.
Example:
.Sp
.Dl rabbitmq-queues peek --vhost Qo a-vhost Qc Qo a-queue Qc Qo 1 Qc
.It Cm check_if_node_is_mirror_sync_critical
.It Cm check_if_cluster_has_classic_queue_mirroring_policy
.Pp
Health check that exits with a non-zero code if there are classic mirrored queues without online synchronised mirrors (queues that would potentially lose data if the target node is shut down).
Health check that exits with a non-zero code if there are policies in the cluster that enable classic queue mirroring.
Classic queue mirroring has been deprecated since 2021 and was completely removed in the RabbitMQ 4.0 development cycle.
.Pp
Example:
.Sp
.Dl rabbitmq-queues check_if_node_is_mirror_sync_critical
.Dl rabbitmq-queues check_if_cluster_has_classic_queue_mirroring_policy
.It Cm check_if_node_is_quorum_critical
.Pp
Health check that exits with a non-zero code if there are queues with minimum online quorum (queues that would lose their quorum if the target node is shut down).
Expand All @@ -210,4 +211,4 @@ Example:
.\" ------------------------------------------------------------------
.Sh AUTHOR
.\" ------------------------------------------------------------------
.An The RabbitMQ Team Aq Mt rabbitmq-core@groups.vmware.com
.An The RabbitMQ Team Aq Mt contact-tanzu-data.pdl@broadcom.com
2 changes: 1 addition & 1 deletion deps/rabbit/docs/rabbitmq-server.8
Original file line number Diff line number Diff line change
Expand Up @@ -96,4 +96,4 @@ For example, runs RabbitMQ AMQP server in the background:
.\" ------------------------------------------------------------------
.Sh AUTHOR
.\" ------------------------------------------------------------------
.An The RabbitMQ Team Aq Mt rabbitmq-core@groups.vmware.com
.An The RabbitMQ Team Aq Mt contact-tanzu-data.pdl@broadcom.com
2 changes: 1 addition & 1 deletion deps/rabbit/docs/rabbitmq-service.8
Original file line number Diff line number Diff line change
Expand Up @@ -150,4 +150,4 @@ is to discard the server output.
.\" ------------------------------------------------------------------
.Sh AUTHOR
.\" ------------------------------------------------------------------
.An The RabbitMQ Team Aq Mt rabbitmq-core@groups.vmware.com
.An The RabbitMQ Team Aq Mt contact-tanzu-data.pdl@broadcom.com
2 changes: 1 addition & 1 deletion deps/rabbit/docs/rabbitmq-streams.8
Original file line number Diff line number Diff line change
Expand Up @@ -447,4 +447,4 @@ for each consumer attached to the stream-1 stream and belonging to the stream-1
.\" ------------------------------------------------------------------
.Sh AUTHOR
.\" ------------------------------------------------------------------
.An The RabbitMQ Team Aq Mt rabbitmq-core@groups.vmware.com
.An The RabbitMQ Team Aq Mt contact-tanzu-data.pdl@broadcom.com
2 changes: 1 addition & 1 deletion deps/rabbit/docs/rabbitmq-upgrade.8
Original file line number Diff line number Diff line change
Expand Up @@ -127,4 +127,4 @@ To learn more, see the
.\" ------------------------------------------------------------------
.Sh AUTHOR
.\" ------------------------------------------------------------------
.An The RabbitMQ Team Aq Mt rabbitmq-core@groups.vmware.com
.An The RabbitMQ Team Aq Mt contact-tanzu-data.pdl@broadcom.com
2 changes: 1 addition & 1 deletion deps/rabbit/docs/rabbitmqctl.8
Original file line number Diff line number Diff line change
Expand Up @@ -2457,4 +2457,4 @@ Reset the stats database for all nodes in the cluster.
.\" ------------------------------------------------------------------------------------------------
.Sh AUTHOR
.\" ------------------------------------------------------------------------------------------------
.An The RabbitMQ Team Aq Mt rabbitmq-core@groups.vmware.com
.An The RabbitMQ Team Aq Mt contact-tanzu-data.pdl@broadcom.com

0 comments on commit 9f47ca5

Please sign in to comment.