From 13b60b8997a10e1d99c6934e9a7b448f04c7c7e2 Mon Sep 17 00:00:00 2001 From: Adam Samalik Date: Jul 12 2018 15:00:12 +0000 Subject: [PATCH 1/12] syntax fixes --- diff --git a/antora.yml b/antora.yml index 2f5c204..c1018bd 100644 --- a/antora.yml +++ b/antora.yml @@ -1,13 +1,10 @@ # Name will be mostly visible in the URL. Treat it as an indentifier. -# Example: modularity -name: # <---- PLEASE MODIFY +name: pizza-factory # <---- PLEASE MODIFY # Title will be visible on the page. -# Example: Fedora Modularity -title: # <---- PLEASE MODIFY +title: Pizza Factory # <---- PLEASE MODIFY # 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. -# Example: f28 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. diff --git a/modules/ROOT/assets/images/pizza.png b/modules/ROOT/assets/images/pizza.png new file mode 100644 index 0000000..bdecba7 Binary files /dev/null and b/modules/ROOT/assets/images/pizza.png differ diff --git a/modules/ROOT/assets/pizza.jpg b/modules/ROOT/assets/pizza.jpg deleted file mode 100644 index 80a46ba..0000000 Binary files a/modules/ROOT/assets/pizza.jpg and /dev/null differ diff --git a/modules/ROOT/pages/faq.adoc b/modules/ROOT/pages/faq.adoc index a9476c8..8a8da48 100644 --- a/modules/ROOT/pages/faq.adoc +++ b/modules/ROOT/pages/faq.adoc @@ -1,7 +1,7 @@ = Frequently Asked Questions (FAQ) [qanda] -Can I see a built preview of this template to get a better idea about the result? +Can I see a built preview of this template to get a better idea about the result?:: Of course you can! Just look at the README of the repository — it should tell you everything. -Is writing documentation hard and dreadful? +Is writing documentation hard and dreadful?:: Absolutely not. Writing documentation in asciidoc is very simple and straighforward. And in fact, writing documentation makes you very happy. Just try and see for yourself! diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index cabea53..f11d625 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -4,4 +4,4 @@ The Pizza Project is a useful project with a very bad name — it helps you with In fact, this is just a source template for a new piece of the Fedora Docs. -image::pizza.jpg +image::pizza.png[Pizza] From 3fbb063d8fd6436daecc0c8014044996ba715bdd Mon Sep 17 00:00:00 2001 From: Adam Samalik <asamalik@redhat.com> Date: Jul 12 2018 15:18:31 +0000 Subject: [PATCH 2/12] describe the structure in readme --- diff --git a/README.md b/README.md index 7f45efa..191c31b 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,28 @@ # Fedora Docs Template This repository contains a minimal source structure for a new Fedora Docs source. + +## Structure + +``` +|-- README.md +|-- antora.yml ....................... 1. +`-- modules + `-- ROOT + |-- assets + | `-- images ............... 2. + | `-- pizza.png + |-- nav.adoc ................. 3. + `-- pages .................... 4. + |-- architecture.adoc + |-- community.adoc + |-- faq.adoc + |-- index.adoc + |-- pizza-dough.adoc + `-- pizza-owen.adoc +``` + +1. Metadata definition. +2. Images to be used on any page. +3. Menu definition. Also defines the hierarchy of all the pages. +4. Pages with the actual content. They can be also organised into subdirectories if desired. From 3ebace894c1d2ba2aa4615ca17d4fd13b570db5f Mon Sep 17 00:00:00 2001 From: Adam Samalik <asamalik@redhat.com> Date: Jul 17 2018 08:38:54 +0000 Subject: [PATCH 3/12] Update README.md --- diff --git a/README.md b/README.md index 191c31b..26fcaf2 100644 --- a/README.md +++ b/README.md @@ -8,12 +8,12 @@ This repository contains a minimal source structure for a new Fedora Docs source |-- README.md |-- antora.yml ....................... 1. `-- modules - `-- ROOT + `-- ROOT ......................... 2. |-- assets - | `-- images ............... 2. + | `-- images ............... 3. | `-- pizza.png - |-- nav.adoc ................. 3. - `-- pages .................... 4. + |-- nav.adoc ................. 4. + `-- pages .................... 5. |-- architecture.adoc |-- community.adoc |-- faq.adoc @@ -23,6 +23,14 @@ This repository contains a minimal source structure for a new Fedora Docs source ``` 1. Metadata definition. -2. Images to be used on any page. -3. Menu definition. Also defines the hierarchy of all the pages. -4. Pages with the actual content. They can be also organised into subdirectories if desired. +2. A "root module of this documentation component". Please read below for an explanation. +3. Images to be used on any page. +4. Menu definition. Also defines the hierarchy of all the pages. +5. Pages with the actual content. They can be also organised into subdirectories if desired. + +== Components and Modules + +Antora introduces two new terms: + +* **Component** — Simply put, a component is a part of the documentation website with its own menu. Components can also be versioned. In the Fedora Docs, we use separate components for user documentation, the Fedora Poject, Fedora council, Mindshare, FESCO, but also subprojects such as CommOps or Modulartity. +* **Module** — A component can be broken down into multiple modules. Modules still share a single menu on the site, but their sources can be stored in different git repositories, even owned by different groups. The default module is called "ROOT" (that's what is in this example). If you don't want to use multiple modules, only use "ROOT". But to define more modules, simply duplicate the "ROOT" directory and name it anything you want. You can store modules in one or more git repositories. From 749e655abf4edb3acb4843f015dce8ea694f9252 Mon Sep 17 00:00:00 2001 From: Adam Samalik <asamalik@redhat.com> Date: Jul 18 2018 10:34:11 +0000 Subject: [PATCH 4/12] Update README.md --- diff --git a/README.md b/README.md index 26fcaf2..ad70b1e 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ This repository contains a minimal source structure for a new Fedora Docs source 4. Menu definition. Also defines the hierarchy of all the pages. 5. Pages with the actual content. They can be also organised into subdirectories if desired. -== Components and Modules +## Components and Modules Antora introduces two new terms: From 8f4cee9dbaec6bf1793db89af68536c5f9a785ef Mon Sep 17 00:00:00 2001 From: Adam Samalik <asamalik@redhat.com> Date: Jul 18 2018 11:00:49 +0000 Subject: [PATCH 5/12] local preview --- diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..9f3ebf5 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +build +cache +public diff --git a/README.md b/README.md index ad70b1e..bbe97d2 100644 --- a/README.md +++ b/README.md @@ -7,13 +7,16 @@ This repository contains a minimal source structure for a new Fedora Docs source ``` |-- README.md |-- antora.yml ....................... 1. +|-- build.sh ......................... 2. +|-- preview.sh ....................... 3. +|-- site.yml ......................... 4. `-- modules - `-- ROOT ......................... 2. + `-- ROOT ......................... 5. |-- assets - | `-- images ............... 3. + | `-- images ............... 6. | `-- pizza.png - |-- nav.adoc ................. 4. - `-- pages .................... 5. + |-- nav.adoc ................. 7. + `-- pages .................... 8. |-- architecture.adoc |-- community.adoc |-- faq.adoc @@ -23,10 +26,34 @@ This repository contains a minimal source structure for a new Fedora Docs source ``` 1. Metadata definition. -2. A "root module of this documentation component". Please read below for an explanation. -3. Images to be used on any page. -4. Menu definition. Also defines the hierarchy of all the pages. -5. Pages with the actual content. They can be also organised into subdirectories if desired. +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. +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. +7. Menu definition. Also defines the hierarchy of all the pages. +8. Pages with the actual content. They can be also organised into subdirectories if desired. + +## Local preview + +This repo includes scripts to build and preview the contents of this repository. 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. + +The scripts use docker, so please make sure you have it installed on your system. Please see below for instructions. + +To build and preview the site, run: + +``` +$ ./build.sh && preview.sh +``` + +The result will be available at http://localhost:8080 + +### Installing docker on Fedora + +``` +$ sudo dnf install docker +$ sudo systemctl start docker && sudo systemctl enable docker +``` ## Components and Modules diff --git a/antora.yml b/antora.yml index c1018bd..3ea0e50 100644 --- a/antora.yml +++ b/antora.yml @@ -1,4 +1,5 @@ # Name will be mostly visible in the URL. Treat it as an indentifier. +# 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: pizza-factory # <---- PLEASE MODIFY # Title will be visible on the page. diff --git a/build.sh b/build.sh new file mode 100755 index 0000000..8cc7857 --- /dev/null +++ b/build.sh @@ -0,0 +1,5 @@ +#!/bin/sh + +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." +sudo docker run --rm -it -v $(pwd):/antora:z antora/antora --html-url-extension-style=indexify site.yml diff --git a/preview.sh b/preview.sh new file mode 100755 index 0000000..c233544 --- /dev/null +++ b/preview.sh @@ -0,0 +1,6 @@ +#!/bin/sh + +echo "" +echo "This script is using Docker launch a local web server in a container. You might be asked for a root password in order to start it." +echo "The preview will be available at http://localhost:8080/en_US/" +sudo docker run --rm -v $(pwd)/public:/usr/share/nginx/html:ro -p 8080:80 nginx diff --git a/site.yml b/site.yml new file mode 100644 index 0000000..96b79fd --- /dev/null +++ b/site.yml @@ -0,0 +1,20 @@ +site: + title: Local Preview + start_page: pizza-factory::index +content: + sources: + - url: . + branches: HEAD +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 From 95e2629f81e872c41798fcd86a3e118bc9323750 Mon Sep 17 00:00:00 2001 From: Adam Samalik <asamalik@redhat.com> Date: Jul 18 2018 11:02:33 +0000 Subject: [PATCH 6/12] highlight the most important info in readme --- diff --git a/README.md b/README.md index bbe97d2..4535fb0 100644 --- a/README.md +++ b/README.md @@ -30,9 +30,9 @@ This repository contains a minimal source structure for a new Fedora Docs source 3. A script that shows a preview of the site in a web browser by running a local web server. Uses docker. 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. -7. Menu definition. Also defines the hierarchy of all the pages. -8. Pages with the actual content. They can be also organised into subdirectories if desired. +6. **Images** to be used on any page. +7. **Menu definition.** Also defines the hierarchy of all the pages. +8. **Pages with the actual content.** They can be also organised into subdirectories if desired. ## Local preview From 7dd0e51fd745391eff04cd59d55b67a04aae7442 Mon Sep 17 00:00:00 2001 From: Adam Samalik <asamalik@redhat.com> Date: Jul 18 2018 11:12:00 +0000 Subject: [PATCH 7/12] don't ask for a root passwd on macOS while running docker --- diff --git a/build.sh b/build.sh index 8cc7857..c9349e3 100755 --- a/build.sh +++ b/build.sh @@ -1,5 +1,16 @@ #!/bin/sh -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." +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. + docker run --rm -it -v $(pwd):/antora antora/antora --html-url-extension-style=indexify site.yml + +elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then + # Running on Linux. + # 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." sudo docker run --rm -it -v $(pwd):/antora:z antora/antora --html-url-extension-style=indexify site.yml +fi diff --git a/preview.sh b/preview.sh index c233544..b2c44d5 100755 --- a/preview.sh +++ b/preview.sh @@ -1,6 +1,17 @@ #!/bin/sh -echo "" -echo "This script is using Docker launch a local web server in a container. You might be asked for a root password in order to start it." +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. + sudo docker run --rm -v $(pwd)/public:/usr/share/nginx/html:ro -p 8080:80 nginx + +elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then + # Running on Linux. + # 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/en_US/" -sudo docker run --rm -v $(pwd)/public:/usr/share/nginx/html:ro -p 8080:80 nginx + sudo docker run --rm -v $(pwd)/public:/usr/share/nginx/html:ro -p 8080:80 nginx +fi From f38a99ea4f320a453e8a0af725d591b91e3ff854 Mon Sep 17 00:00:00 2001 From: Adam Samalik <asamalik@redhat.com> Date: Jul 18 2018 11:13:09 +0000 Subject: [PATCH 8/12] fix a typo --- diff --git a/README.md b/README.md index 4535fb0..fc253a6 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ The scripts use docker, so please make sure you have it installed on your system To build and preview the site, run: ``` -$ ./build.sh && preview.sh +$ ./build.sh && ./preview.sh ``` The result will be available at http://localhost:8080 diff --git a/preview.sh b/preview.sh index b2c44d5..29fa860 100755 --- a/preview.sh +++ b/preview.sh @@ -4,7 +4,7 @@ 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. - sudo docker run --rm -v $(pwd)/public:/usr/share/nginx/html:ro -p 8080:80 nginx + docker run --rm -v $(pwd)/public:/usr/share/nginx/html:ro -p 8080:80 nginx elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then # Running on Linux. From 5289d3b97d8afec0c52e42e081a770c1e5e858a4 Mon Sep 17 00:00:00 2001 From: Adam Samalik <asamalik@redhat.com> Date: Jul 18 2018 11:15:01 +0000 Subject: [PATCH 9/12] show the URL on macOS, too --- diff --git a/preview.sh b/preview.sh index 29fa860..0a6f97d 100755 --- a/preview.sh +++ b/preview.sh @@ -4,6 +4,7 @@ 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/en_US/" docker run --rm -v $(pwd)/public:/usr/share/nginx/html:ro -p 8080:80 nginx elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then @@ -12,6 +13,6 @@ elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then # 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/en_US/" + echo "The preview will be available at http://localhost:8080/en_US/" sudo docker run --rm -v $(pwd)/public:/usr/share/nginx/html:ro -p 8080:80 nginx fi From a1ca2ca66fedc15dea1ba03d8420daa319395dee Mon Sep 17 00:00:00 2001 From: Adam Samalik <asamalik@redhat.com> Date: Jul 18 2018 11:15:45 +0000 Subject: [PATCH 10/12] fix the preview url --- diff --git a/preview.sh b/preview.sh index 0a6f97d..acab783 100755 --- a/preview.sh +++ b/preview.sh @@ -4,7 +4,7 @@ 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/en_US/" + 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 elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then @@ -13,6 +13,6 @@ elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then # 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/en_US/" + 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 fi From f1ea529f9ede71ca21c804fe37ce6d3a300a1304 Mon Sep 17 00:00:00 2001 From: Adam Samalik <asamalik@redhat.com> Date: Jul 18 2018 11:26:46 +0000 Subject: [PATCH 11/12] mention the main build repo in the readme --- diff --git a/README.md b/README.md index fc253a6..e2a774f 100644 --- a/README.md +++ b/README.md @@ -36,9 +36,11 @@ This repository contains a minimal source structure for a new Fedora Docs source ## Local preview -This repo includes scripts to build and preview the contents of this repository. 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. +This repo includes scripts to build and preview the contents of this repository. -The scripts use docker, so please make sure you have it installed on your system. Please see below for instructions. +**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. To build and preview the site, run: From 014ace7590b3dccb00d7d0039cdb0fd04ecc259e Mon Sep 17 00:00:00 2001 From: Adam Samalik <asamalik@redhat.com> Date: Jul 18 2018 11:28:19 +0000 Subject: [PATCH 12/12] rearrange the README --- diff --git a/README.md b/README.md index e2a774f..f1843b3 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,13 @@ This repository contains a minimal source structure for a new Fedora Docs source 7. **Menu definition.** Also defines the hierarchy of all the pages. 8. **Pages with the actual content.** They can be also organised into subdirectories if desired. +## Components and Modules + +Antora introduces two new terms: + +* **Component** — Simply put, a component is a part of the documentation website with its own menu. Components can also be versioned. In the Fedora Docs, we use separate components for user documentation, the Fedora Poject, Fedora council, Mindshare, FESCO, but also subprojects such as CommOps or Modulartity. +* **Module** — A component can be broken down into multiple modules. Modules still share a single menu on the site, but their sources can be stored in different git repositories, even owned by different groups. The default module is called "ROOT" (that's what is in this example). If you don't want to use multiple modules, only use "ROOT". But to define more modules, simply duplicate the "ROOT" directory and name it anything you want. You can store modules in one or more git repositories. + ## Local preview This repo includes scripts to build and preview the contents of this repository. @@ -56,10 +63,3 @@ The result will be available at http://localhost:8080 $ sudo dnf install docker $ sudo systemctl start docker && sudo systemctl enable docker ``` - -## Components and Modules - -Antora introduces two new terms: - -* **Component** — Simply put, a component is a part of the documentation website with its own menu. Components can also be versioned. In the Fedora Docs, we use separate components for user documentation, the Fedora Poject, Fedora council, Mindshare, FESCO, but also subprojects such as CommOps or Modulartity. -* **Module** — A component can be broken down into multiple modules. Modules still share a single menu on the site, but their sources can be stored in different git repositories, even owned by different groups. The default module is called "ROOT" (that's what is in this example). If you don't want to use multiple modules, only use "ROOT". But to define more modules, simply duplicate the "ROOT" directory and name it anything you want. You can store modules in one or more git repositories.