Issues importing and building RabbitMQ OSS docs with the Tanzu docs

pstack2021 commented 2 years ago

@michaelklishin @dyozie

When importing the RabbitMQ OSS website into Tanzu docs, these are the outstanding issues which we should work on - possibly have them fixed for the OSS 3.11/Tanzu 1.4 releases (September timeframe I think)

After copying in the OSS RabbitMQ markdown files into the https://github.com/pivotal/docs-book-tanzu-rmq repo, the copyright information in each OSS Markdown file is obviously copied in also, we don’t need this in Tanzu Docs because there is a standard copyright footer on each Tanzu docs page (https://docs.vmware.com/en/VMware-Tanzu-RabbitMQ/index.html) which is created via the Tanzu docs tool chain. @dyozie has created a shell script to remove this information in the https://github.com/pivotal/docs-book-tanzu-rmq after the copy is complete and before we run the docs build so we have a solution for this one right now - not sure if we would want to change this/why we would want to change it in the future? Any comments? Screenshot attached showing this:

Screenshot 2022-06-14 at 14 51 49

There are still some remaining missing links (but they were there in the 1.2 release also so they are not new now) after we build the OSS docs with the Tanzu docs build system. These are missing links to HTML files (e.g the MAN pages) on the RabbitMQ site or to files that are still generated from XML (SGML) files. The VMWare docs tool chain has no ability to process these files right now so it is not building them - it doesn’t know what to do with them. some screenshots attached

Screenshot 2022-06-14 at 13 32 34 Screenshot 2022-06-14 at 14 23 32

Possible solutions:

We may want to update the script (we could use the same script we are using for 1. above) to change these links to direct links to the RabbitMQ website.
Change these SGML files to MD files in RabbitMQ website

I will setup a meeting to discuss the above, thanks.

michaelklishin commented 2 years ago

Here are the warnings, in text form:

Missing link ./tanzu/ in 'oss/definitions.html'
Missing link .ha.html in 'oss/quorum-queues.html'
Missing link specification.html#tx in 'oss/ha.html'
Missing link ./rabbitmqctl.8.html in 'oss/cli.html'
Missing link ./rabbitmq-diagnostics.8.html in 'oss/cli.html'
Missing link ./rabbitmq-plugins.8.html in 'oss/cli.html'
Missing link ./rabbitmq-queues.8.html in 'oss/cli.html'
Missing link ./rabbitmq-upgrade.8.html in 'oss/cli.html'
Missing link ./rabbitmqctl.8.html in 'oss/cli.html'
Missing link ./rabbitmq-plugins.8.html in 'oss/cli.html'
Missing link ./rabbitmqctl.8.html in 'oss/cli.html'
Missing link ./rabbitmq-diagnostics.8.html in 'oss/monitoring.html'
Missing link ./rabbitmq-diagnostics.8.html in 'oss/monitoring.html'
Missing link ./rabbitmqctl.8.html#stop_app in 'oss/monitoring.html'
Missing link ./rabbitmq-diagnostics.8.html in 'oss/monitoring.html'
Missing link ./rabbitmq-diagnostics.8.html in 'oss/monitoring.html'
Missing link ./rabbitmq-diagnostics.8.html in 'oss/monitoring.html'
Missing link ./rabbitmq-diagnostics.8.html in 'oss/monitoring.html'
Missing link ./rabbitmq-diagnostics.8.html in 'oss/monitoring.html'
Missing link ./rabbitmq-diagnostics.8.html in 'oss/monitoring.html'
Missing link ./rabbitmq-plugins.8.html#list in 'oss/monitoring.html'
Missing link login-session-timeout in 'oss/management.html'
Missing link ./rabbitmqctl.8.html#set_user_tags in 'oss/management.html'
Missing link rabbitmqctl.8.html#delete_user in 'oss/access-control.html'
Missing link rabbitmqctl.8.html#change_password in 'oss/access-control.html'
Missing link rabbitmqctl.8.html in 'oss/access-control.html'
Missing link ./rabbitmqctl.8.html#set_user_tags in 'oss/access-control.html'
Missing link ./rabbitmqctl.8.html#set_permissions in 'oss/vhosts.html'
Missing link uri-spec.html in 'oss/shovel-dynamic.html'
Missing link ./uri-spec.html in 'oss/shovel-dynamic.html'
Missing link ./rabbitmq-diagnostics.8.html in 'oss/configure.html'
Missing link ./rabbitmq-diagnostics.8.html in 'oss/configure.html'
Missing link rabbitmq-queues.8.html in 'oss/upgrade.html'
Missing link rabbitmq-upgrade.8.html in 'oss/upgrade.html'
Missing link rabbitmqctl.8.html#Cluster management in 'oss/changelog.html'
Missing link semantics.html#ordering in 'oss/changelog.html'
Missing link uri-spec.html in 'oss/changelog.html'
Missing link ./resources/RabbitMQ_PressRelease_080207.pdf in 'oss/changelog.html'
Missing link ./uri-spec.html in 'oss/federation.html'
Missing link uri-spec.html in 'oss/federation-reference.html'
Missing link uri-spec.html in 'oss/uri-query-parameters.html'
Missing link &amp;url-dotnet-apidoc;/RabbitMQ.Client.SslOption.html in 'oss/ssl.html'
Missing link specification.html in 'oss/connections.html'
Missing link tanzu in 'oss/networking.html'
Missing link ./tanzu/ in 'oss/clustering-compression.html'
Missing link ./tanzu/ in 'oss/clustering-compression.html'
Missing link tanzu in 'oss/clustering.html'
Missing link ./rabbitmqctl.8.html#reset in 'oss/clustering.html'
Missing link ./rabbitmqctl.8.html#reset in 'oss/clustering.html'
Missing link ./rabbitmqctl.8.html in 'oss/documentation.html'
Missing link ./rabbitmq-diagnostics.8.html in 'oss/documentation.html'
Missing link ./rabbitmq-plugins.8.html in 'oss/documentation.html'
Missing link ./rabbitmq-queues.8.html in 'oss/documentation.html'
Missing link ./uri-spec.html in 'oss/documentation.html'
Missing link amqp-0-9-1-quickref.html in 'oss/documentation.html'
Missing link protocol.html in 'oss/documentation.html'
Missing link amqp-0-9-1-errata.html in 'oss/documentation.html'
Missing link ./rabbitmq-release-signing-key.asc in 'oss/download.html'
Missing link amqp-0-9-1-reference.html#basic.consume in 'oss/consumers.html'
Missing link ./rabbitmqctl.8.html in 'oss/consumers.html'
Missing link ./rabbitmqctl.8.html#list_consumers in 'oss/consumers.html'
Missing link amqp-0-9-1-reference.html#class.basic in 'oss/ttl.html'
Missing link amqp-0-9-1-reference.html#basic.publish in 'oss/ttl.html'
Missing link ../amqp-0-9-1-reference.html in 'oss/tutorials/amqp-concepts.html'
Missing link ../amqp-0-9-1-quickref.html#class.confirm in 'oss/tutorials/amqp-concepts.html'
Missing link ./specification.html in 'oss/nack.html'
Missing link ./amqp-0-9-1-reference.html in 'oss/channels.html'
Missing link ./rabbitmq-diagnostics.8.html in 'oss/channels.html'
Missing link ./rabbitmqctl.8.html in 'oss/channels.html'
Missing link ./rabbitmqctl.8.html in 'oss/channels.html'
Missing link ./rabbitmqctl.8.html in 'oss/channels.html'
Missing link uri-spec.html in 'oss/api-guide.html'
Missing link amqp-0-9-1-quickref.html in 'oss/getstarted.html'
Missing link resources/grails-amqp.pdf in 'oss/devtools.html'
Missing link ./uri-spec.html in 'oss/jms-client.html'
Missing link amqp-0-9-1-quickref.html in 'oss/jms-client.html'
Missing link ./uri-spec.html in 'oss/dotnet-api-guide.html'
Missing link ./specification.html in 'oss/dotnet-api-guide.html'
Missing link ./amqp-0-9-1-quickref.html in 'oss/erlang-client-user-guide.html'
Missing link ./uri-spec.html in 'oss/erlang-client-user-guide.html'
Missing link ./specification.html in 'oss/erlang-client-user-guide.html'
Missing link amqp-0-9-1-errata.html#section_3 in 'oss/amqp-wireshark.html'
Missing link specification.html in 'oss/extensions.html'
Missing link ./amqp-0-9-1-reference.html#connection.update-secret in 'oss/extensions.html'
Missing link ./spec-differences.html in 'oss/extensions.html'
Missing link ./amqp-0-9-1-errata.html in 'oss/extensions.html'
Missing link ./amqp-0-9-1-reference.html#domain.longstr in 'oss/sender-selected.html'
Missing link ./rabbitmq-diagnostics.8.html in 'oss/troubleshooting-ssl.html'
Missing link ./rabbitmq-diagnostics.8.html in 'oss/troubleshooting-ssl.html'
Missing link /rabbitmq-diagnostics.8.html in 'oss/troubleshooting-networking.html'
Missing link /rabbitmq-diagnostics.8.html in 'oss/troubleshooting-networking.html'
Missing link /rabbitmq-diagnostics.8.html in 'oss/troubleshooting-networking.html'
Missing link /rabbitmq-diagnostics.8.html in 'oss/troubleshooting-networking.html'
Missing link /rabbitmq-diagnostics.8.html in 'oss/troubleshooting-networking.html'
Missing link /rabbitmq-diagnostics.8.html in 'oss/troubleshooting-networking.html'
Missing link /rabbitmq-diagnostics.8.html in 'oss/troubleshooting-networking.html'
Missing link /rabbitmqctl.8.html in 'oss/troubleshooting-networking.html'
Missing link /rabbitmqctl.8.html in 'oss/troubleshooting-networking.html'
Missing link /rabbitmq-diagnostics.8.html in 'oss/troubleshooting-networking.html'
Missing link /rabbitmqctl.8.html in 'oss/troubleshooting-networking.html'
Missing link ../../rabbitmq-queues.8.html#rebalance in 'oss/kubernetes/operator/using-operator.html'
Missing link ../..//rabbitmq-queues.8.html#check_if_node_is_quorum_critical in 'oss/kubernetes/operator/using-operator.html'
Missing link ../../rabbitmq-queues.8.html#check_if_node_is_mirror_sync_critical in 'oss/kubernetes/operator/using-operator.html'
Missing link clustering.html#ports in 'oss/kubernetes/operator/using-operator.html'
Missing link ../../rabbitmq-diagnostics.8.html in 'oss/kubernetes/operator/kubectl-plugin.html'
Missing link rabbitmqctl.8.html in 'oss/admin-guide.html'
Missing link rabbitmq-diagnostics.8.html in 'oss/admin-guide.html'
Missing link rabbitmq-plugins.8.html in 'oss/admin-guide.html'
Missing link rabbitmq-queues.8.html in 'oss/admin-guide.html'
Missing link rabbitmq-env.conf.5.html in 'oss/manpages.html'
Missing link rabbitmqctl.8.html in 'oss/manpages.html'
Missing link rabbitmq-diagnostics.8.html in 'oss/manpages.html'
Missing link rabbitmq-plugins.8.html in 'oss/manpages.html'
Missing link rabbitmq-upgrade.8.html in 'oss/manpages.html'
Missing link rabbitmq-queues.8.html in 'oss/manpages.html'
Missing link rabbitmq-server.8.html in 'oss/manpages.html'
Missing link rabbitmq-service.8.html in 'oss/manpages.html'
Missing link rabbitmq-echopid.8.html in 'oss/manpages.html'
Missing link amqp-0-9-1-reference.html#class.basic in 'oss/firehose.html'
Missing link &amp;dir-current-javadoc; in 'oss/clients.html'
Missing link &amp;url-dotnet-apidoc;/RabbitMQ.Client.html in 'oss/clients.html'
Missing link uri-spec.html in 'oss/clients.html'
Missing link ./uri-spec.html in 'oss/shovel-static.html'
Missing link ./uri-spec.html in 'oss/shovel-static.html'
Missing link ./tanzu/ in 'oss/definitions-standby.html'
Missing link ./tanzu/ in 'oss/definitions-standby.html'
Missing link /tanzu/ in 'tanzu/clustering-compression-rabbitmq.html'
Missing link /clustering.html in 'tanzu/clustering-compression-rabbitmq.html'
Missing link /cli.html in 'tanzu/clustering-compression-rabbitmq.html'
Missing link /clustering-ssl.html in 'tanzu/clustering-compression-rabbitmq.html'
Missing link /tanzu/ in 'tanzu/clustering-compression-rabbitmq.html'
Missing link /cluster-formation.html in 'tanzu/clustering-compression-rabbitmq.html'

michaelklishin commented 2 years ago

These links can be grouped and addressed in several ways, per our conversation with @pstack2021 and @dyozie.

Old Release Notes

They have been moved to the server repo, rabbitmq/rabbitmq-server. As of https://github.com/rabbitmq/rabbitmq-website/commit/916941215d0d400c1397cc570ae560efa108126b we point links to old release notes to GitHub. This was a genuine case of a 404 link in the OSS repo.

Tanzu-specific Content

Everything under the ./tanzu directory is Tanzu-specific and should be folded into the Tanzu docs repository, then removed from the OSS site (or rather, changed to use external links).

Old Protocol Docs

These can be removed or ignored by the Tanzu docs site. Some links also be removed from the OSS site.

amqp-0-9-1-reference.html
amqp-0-9-1-quickref.html
amqp-0-9-1-errata.html
specification.html
protocol.html
./resources/RabbitMQ_PressRelease_080207.pdf
spec-differences.html

Man Pages

We should forward these man page links to the OSS site:

rabbitmqctl.8.html
rabbitmq-diagnostics.8.html
rabbitmq-plugins.8.html
rabbitmq-env.conf.5.html
rabbitmqctl.8.html
rabbitmq-upgrade.8.html
rabbitmq-queues.8.html
rabbitmq-server.8.html
rabbitmq-service.8.html
rabbitmq-echopid.8.html

Genuine Broken OSS Site Links

Some links seem to be genuinely broken in this site. There are relatively few of them, I will take care of that very soon.

Guides that Can be Moved to Markdown

I have moved one more guide to Markdown and looking at porting a couple more.

michaelklishin commented 2 years ago

A little update on man pages. The only reason why we have DocBook files for them is to provide a "wrapper" for the HTML pages we generate from ntroff and sync to site/man.

I think forwarding them to rabbitmq.com is the easiest solution for now.

The following remaining DocBook files are irrelevant to Tanzu and can be excluded one way or another:

site/amqp-0-8-to-0-9-1.xml
site/amqp-0-9-1-errata.xml
site/amqp-0-9-1-quickref.xml
site/amqp-0-9-1-reference.xml
site/features.xml
site/how.xml
site/index.xml
site/interoperability.xml
site/news.xml
site/protocol.xml
site/rabbitmq-diagnostics.8.xml
site/rabbitmq-echopid.8.xml
site/rabbitmq-env.conf.5.xml
site/rabbitmq-plugins.8.xml
site/rabbitmq-queues.8.xml
site/rabbitmq-server.8.xml
site/rabbitmq-service.8.xml
site/rabbitmq-upgrade.8.xml
site/rabbitmqctl.8.xml
site/search.xml
site/semantics.xml
site/sitemap.xml
site/spec-differences.xml
site/specification.xml

We can convert some of them to Markdown but not others (without completely switching website generator tooling).

pstack2021 commented 2 years ago

Thanks @michaelklishin, @dyozie and I will work on actions from our side and keep you posted here.

pstack2021 commented 2 years ago

@dyozie closing this issue now as links are fixed and we have a solution to 1. above, please reopen and comment if you think otherwise - thanks.

michaelklishin commented 2 years ago

@pstack2021 I assume you've meant to close this ;) if not please re-open

rabbitmq / rabbitmq-website