mwinters/docs-team-docs
1
0
Fork 0
forked from docs/team-docs
Code Pull requests Activity

Preview script channges from https://pagure.io/fedora-docs/template/pull-request/4

Browse source 
and description on how to use a local server
with the regular Antora Workflow
This commit is contained in:
ojn 2018-09-21 17:49:59 +02:00
commit 801aafd8a7
3 changed files with 67 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

34
modules/contributing/pages/local-preview.adoc
View file

@ -3,9 +3,41 @@
= Building a local preview
Because the documentation site is using a markup language instead of a WYSIWYG editor, the sources do not look exactly like the rendered page will. Therefore it is necessary to check that your changes look the way you want them to before you push and make a merge request. This involves building a local preview.
There are two shell scripts available in each existing repository (including the template repository used to create new content): `build.sh` and `preview.sh`. To preview, run the `build.sh` script; this is the one that actually builds a local version of the site (or, more precisely, the subset of the full site that resides in your current repository). Then, run `preview.sh`, which starts a webserver and serves the site at link:http://localhost:8080/[]. Opening this URL in any web browser will show you the preview, which will be available until you kill the process (kbd:[Ctrl+C] in the terminal).
There are two shell scripts available in each existing repository (including the template repository used to create new content): `build.sh` and docker`preview.sh`.
To preview, run the `build.sh` script; this is the one that actually builds a local version of the site (or, more precisely, the subset of the full site that resides in your current repository). Then, run `preview.sh`, which starts a webserver and serves the site at link:http://localhost:8080/[]. Opening this URL in any web browser will show you the preview, which will be available until you kill the process (kbd:[Ctrl+C] in the terminal).
[NOTE]
====
Running both scripts requires a working [application]`Docker` setup. Each script may also ask for your `root` or user password.
====
== Using the regular Antora scripts
If you want to use the regular Antora build and preview workflow - follow the instructions on https://docs.antora.org/[Antora Documentation page].
Once you have ``Antora CLI`` and ``Antora Site Generator`` you can build and preview the pages without the container scripts.
To build the pages in the project directory run:
[source]
----
antora generate site.yml
----
This will create a new directory ``public`` which contains all the nessesary files. Navigate there and run a server command. You might allready have a Python simple server, in which case run:
[source]
----
python3 -m http.server
----
or if you only have Python 2 on your machine:
[source]
----
python -m SimpleHTTPServer
----
It opens a local preview at port 8000.
If you have cargo (Rust package manager), you could also install and use ``miniserve`` or any other simple server of your choice for that matter.

14
nginx.conf Normal file
View file

@ -0,0 +1,14 @@
server {
listen 80;
server_name localhost;
location / {
root /antora/public;
index index.html index.htm;
}
error_page 500 502 503 504 /50x.html;
location = /50x.html {
root /usr/share/nginx/html;
}
}

27
preview.sh
View file

@ -1,18 +1,31 @@
#!/bin/sh
if [ "$(uname)" == "Darwin" ]; then
# Running on macOS.
# Running on macOS. <1>
# 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)/public:/usr/share/nginx/html:ro -p 8080:80 nginx
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.
# Running on Linux. <2>
# Let's assume that it's running the Docker deamon
# which requires root.
echo ""
echo "This build script is using Docker to run the build in an isolated environment. You might be asked for a root password in order to start it."
echo "The preview will be available at http://localhost:8080/"
sudo docker run --rm -v $(pwd)/public:/usr/share/nginx/html:ro -p 8080:80 nginx
if groups | grep -wq "docker"; then
# Check if the current user is in the "docker" group. If true, no sudo is needed.
echo ""
echo "This build script is using Docker to run the build in an isolated environment."
echo "The preview will be available at http://localhost:8080/"
echo ""
docker run --rm -v $(pwd):/antora:ro,z -v $(pwd)/nginx.conf:/etc/nginx/conf.d/default.conf:ro,z -p 8080:80 nginx
else
# User isn't in the docker group; run the command with sudo. <3>
echo ""
echo "This build script is using Docker 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 ""
echo "The preview will be available at http://localhost:8080/"
echo ""
sudo docker run --rm -v $(pwd):/antora:ro,z -v $(pwd)/nginx.conf:/etc/nginx/conf.d/default.conf:ro,z -p 8080:80 nginx
fi
fi