From b058593d87ade2b84bb187d1a299e73e408def91 Mon Sep 17 00:00:00 2001 From: Adam Samalik Date: Jul 27 2018 12:57:07 +0000 Subject: switch to Antora --- 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 62fdf1e..f1843b3 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,65 @@ -# Fedora Docs Templates +# Fedora Docs Template -Creating a new information/docs repo for use with the docs.fedoraproject.org tooling? Copy the best files for you and have fun. +This repository contains a minimal source structure for a new Fedora Docs source. -- generic: Useful for projects that are not publishing Fedora release specific information -- doc_guide: Useful for projects that are publishing Fedora release specific information +## Structure + +``` +|-- README.md +|-- antora.yml ....................... 1. +|-- build.sh ......................... 2. +|-- preview.sh ....................... 3. +|-- site.yml ......................... 4. +`-- modules + `-- 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. +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. + +## 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. + +**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: + +``` +$ ./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 +``` diff --git a/antora.yml b/antora.yml new file mode 100644 index 0000000..3ea0e50 --- /dev/null +++ b/antora.yml @@ -0,0 +1,16 @@ +# 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. +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. +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 + +# This lists all the menu definitions of your component. +nav: +- modules/ROOT/nav.adoc diff --git a/build.sh b/build.sh new file mode 100755 index 0000000..c9349e3 --- /dev/null +++ b/build.sh @@ -0,0 +1,16 @@ +#!/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. + 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/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/nav.adoc b/modules/ROOT/nav.adoc new file mode 100644 index 0000000..a4054d4 --- /dev/null +++ b/modules/ROOT/nav.adoc @@ -0,0 +1,5 @@ +* xref:architecture.adoc[Architecture] +** xref:pizza-owen.adoc[Pizza Owen] +** xref:pizza-dough.adoc[Pizza Dough] +* xref:community.adoc[Community] +* xref:faq.adoc[FAQ] diff --git a/modules/ROOT/pages/architecture.adoc b/modules/ROOT/pages/architecture.adoc new file mode 100644 index 0000000..97c3e57 --- /dev/null +++ b/modules/ROOT/pages/architecture.adoc @@ -0,0 +1,3 @@ += Pizza Factory Architecture + +The architecture of our pizza factory is quite simple. We bake our very expensive xref:pizza-dough.adoc[pizza dough] in a very cheap xref:pizza-owen.adoc[pizza owen]. This way, we can achieve a medicore result for a high price and a reasonable number of failures. diff --git a/modules/ROOT/pages/community.adoc b/modules/ROOT/pages/community.adoc new file mode 100644 index 0000000..def9977 --- /dev/null +++ b/modules/ROOT/pages/community.adoc @@ -0,0 +1,3 @@ += Pizza Factory Community + +Our community is basically the same as the community of Fedora Docs. That's mostly because this is a template for new pieces of the Fedora Docs. diff --git a/modules/ROOT/pages/faq.adoc b/modules/ROOT/pages/faq.adoc new file mode 100644 index 0000000..8a8da48 --- /dev/null +++ b/modules/ROOT/pages/faq.adoc @@ -0,0 +1,7 @@ += Frequently Asked Questions (FAQ) + +[qanda] +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?:: + 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 new file mode 100644 index 0000000..f11d625 --- /dev/null +++ b/modules/ROOT/pages/index.adoc @@ -0,0 +1,7 @@ += The Pizza Project + +The Pizza Project is a useful project with a very bad name — it helps you with writing some new documentation for Fedora. + +In fact, this is just a source template for a new piece of the Fedora Docs. + +image::pizza.png[Pizza] diff --git a/modules/ROOT/pages/pizza-dough.adoc b/modules/ROOT/pages/pizza-dough.adoc new file mode 100644 index 0000000..5b59bae --- /dev/null +++ b/modules/ROOT/pages/pizza-dough.adoc @@ -0,0 +1,3 @@ += Pizza Dough Architecture + +I would never thought that a pizza dough can have an architecture. Yet here we are. diff --git a/modules/ROOT/pages/pizza-owen.adoc b/modules/ROOT/pages/pizza-owen.adoc new file mode 100644 index 0000000..b15ebaf --- /dev/null +++ b/modules/ROOT/pages/pizza-owen.adoc @@ -0,0 +1,3 @@ += Pizza Owen Architecture + +Pizza owen architecture would be described on this page. Since this is just a template, I choose to disappoint you and not describe the pizza owen architecture. diff --git a/preview.sh b/preview.sh new file mode 100755 index 0000000..acab783 --- /dev/null +++ b/preview.sh @@ -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)/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/" + sudo docker run --rm -v $(pwd)/public:/usr/share/nginx/html:ro -p 8080:80 nginx +fi 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