From 41139d3337df8e71fad4ae7ab44c83884b348673 Mon Sep 17 00:00:00 2001 From: Justin W. Flory (he/him) Date: Feb 19 2021 13:37:03 +0000 Subject: Initial commit, Fedora Web Development SIG documentation This commit initializes a new Fedora Docs repository for the recently- launched Web Development SIG. The content here is a placeholder until we get more of our scope documented. Signed-off-by: Justin W. Flory (he/him) --- 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/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..ba8d521 --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,10 @@ +The text of and illustrations in this document are licensed by Red Hat +under a Creative Commons Attribution–Share Alike 3.0 Unported license +("CC-BY-SA"). An explanation of CC-BY-SA is available at +http://creativecommons.org/licenses/by-sa/3.0/. In accordance with +CC-BY-SA, if you distribute this document or an adaptation of it, you +must provide the URL for the original version. + +Red Hat, as the licensor of this document, waives the right to +enforce, and agrees not to assert, Section 4d of CC-BY-SA to the +fullest extent permitted by applicable law. diff --git a/README.md b/README.md new file mode 100644 index 0000000..1f077dc --- /dev/null +++ b/README.md @@ -0,0 +1,148 @@ +Fedora Web Development SIG +========================== + +Default repository for tracking on-going work in the Fedora Web Development SIG. +Official docs.fp.o documentation also found here. + +## About + +## Contributing to documentation + +The following sections explain how the Fedora Documentation hosted in this repository works. +Guidelines on how to run a local development environment are also below. + +### 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-oven.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 Project, 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 work on Fedora (using Podman) and macOS (using Docker). +To build and preview the site, run: + +```sh +./build.sh && ./preview.sh +``` + +The result will be available at [localhost:8080](http://localhost:8080). + +#### Installing Podman on Fedora + +Fedora 32 Workstation and earlier did not include Podman preinstalled by default. +You may need to install it using the following command: + +```sh +sudo dnf install podman +``` + +#### Preview as a part of the whole Fedora Docs site + +You can also build the whole Fedora Docs site locally to see your changes in the whole context. +This is especially useful for checking if your `xref` links work properly. + +To do this, you need to clone the main [Fedora Docs build repository](https://pagure.io/fedora-docs/docs-fp-o), modify the `site.yml` file to reference a repo with your changes, and build it. + +**Steps**: + +Clone the main repository and `cd` into it: + +```sh +git clone https://pagure.io/fedora-docs/docs-fp-o.git +cd docs-fp-o +``` + +Find a reference to the repository you're changing in the `site.yml` file, and change it so it points to your change. +So for example, if I made a modification to the Modularity docs, I would find: + +```yaml +... + - url: https://pagure.io/fedora-docs/modularity.git + branches: + - main +... +``` + +And replaced it with a pointer to my fork: + +```yaml +... + - url: https://pagure.io/forks/asamalik/fedora-docs/modularity.git + branches: + - master +... +``` + +I could also point to a local repository, using `HEAD` as a branch to preview the what's changed without the need of making a commit. + +**Note:** +I would need to move the repository under the `docs-fp-o` directory, because the builder won't see anything above. +So I would need to create a `repositories` directory in `docs-fp-o` and copy my repository into it. + +```yaml +... + - url: ./repositories/modularity + branches: + - HEAD +... +``` + +To build the whole site, I would run the following in the `docs-fp-o` directory. + +```sh +./build.sh && ./preview.sh +``` diff --git a/antora.yml b/antora.yml new file mode 100644 index 0000000..65b13da --- /dev/null +++ b/antora.yml @@ -0,0 +1,16 @@ +# 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) +name: sig-webdev + +# Title will be visible on the page. +title: Web Development SIG + +# 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..f4ecfe4 --- /dev/null +++ b/build.sh @@ -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 fall 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 diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc new file mode 100644 index 0000000..06683ac --- /dev/null +++ b/modules/ROOT/nav.adoc @@ -0,0 +1 @@ +* https://pagure.io/fedora-commops/issue/225[fedora-commops#225] diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc new file mode 100644 index 0000000..e87007d --- /dev/null +++ b/modules/ROOT/pages/index.adoc @@ -0,0 +1,27 @@ +include::ROOT:partial$attributes.adoc[] + += Fedora Web Development SIG +Justin W. Flory, Ramya Parimi, Akashdeep Dhari +:page-authors: {author}, {author_2}, {author_3} + +Official documentation for the Fedora Web Development SIG. + +:toc: + + +[[about]] +== About the SIG + +Coming soon. + + +[[projects]] +== Projects + +Coming soon. + + +[[contact]] +== Get in touch + +Coming soon. diff --git a/modules/ROOT/partials/attributes.adoc b/modules/ROOT/partials/attributes.adoc new file mode 100644 index 0000000..5ab8049 --- /dev/null +++ b/modules/ROOT/partials/attributes.adoc @@ -0,0 +1,7 @@ +:COMMBLOG: https://communityblog.fedoraproject.org +//:MAILING-LIST: https://lists.fedoraproject.org/admin/lists/i3wm.lists.fedoraproject.org/ +:FWIKI: https://fedoraproject.org/wiki +:MAJOROSVER: 34 +//:MATRIX: https://app.element.io/#/room/#fedora-i3:matrix.org +//:TELEGRAM: https://telegram.me/FedoraI3SIG +:YEAR: 2021 diff --git a/nginx.conf b/nginx.conf new file mode 100644 index 0000000..f7093b3 --- /dev/null +++ b/nginx.conf @@ -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; + } +} diff --git a/preview.sh b/preview.sh new file mode 100755 index 0000000..4270107 --- /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):/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 diff --git a/site.yml b/site.yml new file mode 100644 index 0000000..5d215b7 --- /dev/null +++ b/site.yml @@ -0,0 +1,20 @@ +site: + title: Web Development SIG (local preview) + start_page: sig-webdev::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