PR#5: Import scripts to build & preview locally and update the README. - fedora-badges/docs

fedora-badges / docs

#5 Import scripts to build & preview locally and update the README.

Merged 2 years ago by gui1ty. Opened 2 years ago by troycurtisjr.

fedora-badges/ troycurtisjr/docs add-build-scripts into master

Import scripts to build & preview locally and update the README.

Troy Curtis Jr • 2 years ago

3b23361

.gitignore

file added

		`@@ -0,0 +1,3 @@`
		`+ /build`
		`+ /cache`
		`+ /public`

README.md

file modified

+7 -16

		`@@ -1,6 +1,4 @@`
		`- # Fedora Docs Template`
		`-`
		`- This repository contains a minimal source structure for a new Fedora Docs source.`
		`+ # Fedora Docs for Fedora Badges`

		`## Structure`

		`@@ -14,20 +12,14 @@`
		`-- ROOT ......................... 5.
		`\|-- assets`
		\| `-- images ............... 6.
		- \| `-- pizza.png
		`\|-- nav.adoc ................. 7.`
		`-- pages .................... 8.
		`- \|-- architecture.adoc`
		`- \|-- community.adoc`
		`- \|-- faq.adoc`
		`- \|-- index.adoc`
		`- \|-- pizza-dough.adoc`
		- `-- pizza-owen.adoc
		+ `-- ...
		```

		`1. Metadata definition.`
		`- 2. A script that does a local build. Uses docker.`
		`- 3. A script that shows a preview of the site in a web browser by running a local web server. Uses docker.`
		`+ 2. A script that does a local build. Uses podman or docker.`
		`+ 3. A script that shows a preview of the site in a web browser by running a local web server.`
		`4. A definition file for the build script.`
		`5. A "root module of this documentation component". Please read below for an explanation.`
		`6. Images to be used on any page.`
		`@@ -47,7 +39,7 @@`

		`NOTE: Please note that if you reference pages from other repositoreis, such links will be broken in this local preview as it only builds this repository. If you want to rebuild the whole Fedora Docs site, please see [the Fedora Docs build repository](https://pagure.io/fedora-docs/docs-fp-o/) for instructions.`

		`- Both scripts use docker, so please make sure you have it installed on your system. Please see below for instructions.`
		`+ Both scripts use podman or docker, so please make sure you have one of them installed on your system. Please see below for instructions.`

		`To build and preview the site, run:`

		`@@ -57,11 +49,10 @@`

		`The result will be available at http://localhost:8080`

		`- ### Installing docker on Fedora`
		`+ ### Installing podman on Fedora`

		```
		`- $ sudo dnf install docker`
		`- $ sudo systemctl start docker && sudo systemctl enable docker`
		`+ $ sudo dnf install podman`
		```

		`### Preview as a part of the whole Fedora Docs site`

build.sh

file added

+46

		`@@ -0,0 +1,46 @@`
		`+ #!/bin/sh`
		`+`
		`+ image="docker.io/antora/antora"`
		`+ cmd="--html-url-extension-style=indexify site.yml"`
		`+`
		`+ 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`
		`+`
		`+ elif [ "$(expr substr "$(uname -s)" 1 5)" = "Linux" ]; then`
		`+ # Running on Linux.`
		`+ # Check whether podman is available, else fail back to docker`
		`+ # which requires root.`
		`+`
		`+ if [ -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`
		`+`
		`+ elif [ -f /usr/bin/docker ]; then`
		`+ echo ""`
		`+ echo "This build script is using Docker to run the build in an isolated environment."`
		`+ echo ""`
		`+`
		`+ if groups \| grep -wq "docker"; then`
		`+ 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`
		`+ fi`
		`+ else`
		`+ echo ""`
		`+ echo "Error: Container runtime haven't been found on your system. Fix it by:"`
		`+ echo "$ sudo dnf install podman"`
		`+ exit 1`
		`+ fi`
		`+ fi`

preview.sh

file added

+18

		`@@ -0,0 +1,18 @@`
		`+ #!/bin/sh`
		`+`
		`+ 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 "The preview will be available at http://localhost:8080/"`
		`+ docker run --rm -v "$(pwd):/antora:ro" -v "$(pwd)/nginx.conf:/etc/nginx/conf.d/default.conf:ro" -p 8080:80 nginx`
		`+`
		`+ elif [ "$(expr substr "$(uname -s)" 1 5)" = "Linux" ]; then`
		`+ # Running on Linux.`
		`+ # Fedora Workstation has python3 installed as a default, so using that`
		`+ echo ""`
		`+ echo "The preview is available at http://localhost:8080"`
		`+ echo ""`
		`+ cd ./public`
		`+ python3 -m http.server 8080`
		`+ fi`

site.yml

file added

+21

		`@@ -0,0 +1,21 @@`
		`+ site:`
		`+ title: Fedora Badges (Local Preview)`
		`+ start_page: badges::index`
		`+ content:`
		`+ sources:`
		`+ - url: .`
		`+ branches: HEAD`
		`+ start_path: .`
		`+ ui:`
		`+ bundle:`
		`+ url: https://asamalik.fedorapeople.org/ui-bundle.zip`
		`+ snapshot: true`
		`+ default_layout: with_menu`
		`+ output:`
		`+ clean: true`
		`+ dir: ./public`
		`+ destinations:`
		`+ - provider: archive`
		`+ runtime:`
		`+ pull: true`
		`+ cache_dir: ./cache`

troycurtisjr commented 2 years ago

I noticed none of the build scripts were in the repo and the README was still the original template. I imported the scripts from one of the other docs repos.