PR#53: Antora 3.0 related updates - fedora-docs/package-maintainer-docs

fedora-docs / package-maintainer-docs

#53 Antora 3.0 related updates

Closed 2 years ago by oturpe. Opened 2 years ago by siosm.

fedora-docs/ siosm/package-maintainer-docs antora3 into main

*.yaml: Minor styling fixes

Timothée Ravier • 2 years ago

f4d973c

Package_Retirement_Process: Fix link to Upstream release monitoring

Timothée Ravier • 2 years ago

cdd4160

build.sh: Update with latest version from template

Timothée Ravier • 2 years ago

0b2c569

Update configuration for Antora 3.0

Timothée Ravier • 2 years ago

661dc2d

antora.yml

file modified

+11 -5

		`@@ -1,15 +1,21 @@`
		`# Name will be mostly visible in the URL. Treat it as an identifier.`
		`- # Tip: If you want to use the local preview scripts that come with this repository, please change this value in the site.yml file as well. (under site/start_page)`
		`+ # Tip: If you want to use the local preview scripts that come with this`
		`+ # repository, please change this value in the site.yml file as well. (under`
		`+ # site/start_page)`
		`name: package-maintainers`

		`- # Title will be visible on the page.`
		`+ # Title will be visible on the page.`
		`title: Package Maintainers`

		`- # If you don't plan to have multiple versions of the docs (for example, to document multiple versions of some software), you can ignore this field. Otherwise, change "master" to a specific version.`
		`+ # If you don't plan to have multiple versions of the docs (for example, to`
		`+ # document multiple versions of some software), you can ignore this field.`
		`+ # Otherwise, change "master" to a specific version.`
		`version: master`

		`- # We encourage you to name the index page as "index.adoc". If you absolutely have to use a different name, please reflect it here. You can ignore this field otherwise.`
		`- start_page: ROOT:index`
		`+ # We encourage you to name the index page as "index.adoc". If you absolutely`
		`+ # have to use a different name, please reflect it here. You can ignore this`
		`+ # field otherwise.`
		`+ start_page: ROOT:index.adoc`

		`# This lists all the menu definitions of your component.`
		`nav:`

build.sh

file modified

+13 -8

		`@@ -3,25 +3,30 @@`
		`image="docker.io/antora/antora"`
		`cmd="--html-url-extension-style=indexify site.yml"`

		`- if [ "$(uname)" = "Darwin" ]; then`
		`+ if [ "$(uname)" == "Darwin" ]; then`
		`# Running on macOS.`
		`# Let's assume that the user has the Docker CE installed`
		`# which doesn't require a root password.`
		`echo ""`
		`echo "This build script is using Docker container runtime to run the build in an isolated environment."`
		`echo ""`
		`- docker run --rm -it -v "$(pwd):/antora" $image $cmd`
		`+ docker run --rm -it -v $(pwd):/antora $image $cmd`

		`- elif [ "$(expr substr "$(uname -s)" 1 5)" = "Linux" ]; then`
		`+ elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then`
		`# Running on Linux.`
		`- # Check whether podman is available, else fall back to docker`
		`+ # there isn't an antora/aarch64 container, antora can be installed locally`
		`+ # Check whether podman is available, else faill back to docker`
		`# which requires root.`

		`- if [ -f /usr/bin/podman ]; then`
		`+ if [ -f /usr/local/bin/antora ]; then`
		`+ /usr/local/bin/antora $cmd`
		+ elif [[ `uname -m` == "aarch64" ]]; then
		+ echo "no antora/aarch64 container try just \`npm install -g @antora/cli @antora/site-generator-default\`"
		`+ elif [ -f /usr/bin/podman ]; then`
		`echo ""`
		`echo "This build script is using Podman to run the build in an isolated environment."`
		`echo ""`
		`- podman run --rm -it -v "$(pwd):/antora:z" $image $cmd`
		`+ podman run --rm -it -v $(pwd):/antora:z $image $cmd`

		`elif [ -f /usr/bin/docker ]; then`
		`echo ""`
		`@@ -29,13 +34,13 @@`
		`echo ""`

		`if groups \| grep -wq "docker"; then`
		`- docker run --rm -it -v "$(pwd):/antora:z" $image $cmd`
		`+ docker run --rm -it -v $(pwd):/antora:z $image $cmd`
		`else`
		`echo ""`
		`echo "This build script is using $runtime to run the build in an isolated environment. You might be asked for your password."`
		`echo "You can avoid this by adding your user to the 'docker' group, but be aware of the security implications. See https://docs.docker.com/install/linux/linux-postinstall/."`
		`echo ""`
		`- sudo docker run --rm -it -v "$(pwd):/antora:z" $image $cmd`
		`+ sudo docker run --rm -it -v $(pwd):/antora:z $image $cmd`
		`fi`
		`else`
		`echo ""`

modules/ROOT/pages/Package_Retirement_Process.adoc

file modified

+1 -1

		`@@ -59,7 +59,7 @@`
		`[#upstream_release_monitoring]`
		`=== Upstream Release Monitoring`

		`- Remove the package from xref:Upstream_release_monitoring.adco[Upstream release monitoring] if it is listed.`
		`+ Remove the package from xref:Upstream_Release_Monitoring.adoc[Upstream release monitoring] if it is listed.`

		`=== Koji`

site.yml

file modified

+7 -7

		`@@ -1,6 +1,6 @@`
		`- site:`
		`+ site:`
		`title: Local Preview`
		`- start_page: package-maintainers::index`
		`+ start_page: package-maintainers::index.adoc`
		`content:`
		`sources:`
		`- url: .`
		`@@ -10,11 +10,11 @@`
		`url: https://asamalik.fedorapeople.org/ui-bundle.zip`
		`snapshot: true`
		`default_layout: with_menu`
		`- output:`
		`- clean: true`
		`+ output:`
		`+ clean: true`
		`dir: ./public`
		`- destinations:`
		`- - provider: archive`
		`+ destinations:`
		`+ - provider: archive`
		`runtime:`
		`- pull: true`
		`+ fetch: true`
		`cache_dir: ./cache`

siosm commented 2 years ago

See https://pagure.io/fedora-docs/docs-fp-o/pull-request/178

oturpe commented 2 years ago

Thank you! Mostly, this looks great.

I do not like commit build.sh: Update with latest version from template
which, unfortunately, makes some things worse.
This original works when present working directory path contains whitespace:
podman run --rm -it -v "$(pwd):/antora:z" $image $cmd,
while the suggested alternative without the quotes does not.

Similar problem may also come from removing the inner quotes from this line:
elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then,
depending on if uname -s may contain whitespace.

(If you really hate quoting,
then there are also places in build.sh where they actually can be removed,
like "Linux"in the example above.
But when it comes to shell, usually more quotes are better than less,
for both readability and correct function in presence of strings that contain whitespace.)

I would also have used version: ~in antora.yml,
because the current value master is now deprecated.

I will pull in the other commits
and submit a pull request for the template to fix the mentioned issues.
After the template is good again,
we can then update this repo to match it.

oturpe commented 2 years ago

The PR: template/pull-request/20

oturpe commented 2 years ago

Closing this now,
if you think that the commit I dropped really should be merged,
please open a new one and explain the situation.