PR#649: Add docs.fedoraproject.org structure for future publishing of Badges docs - fedora-badges

fedora-badges

#649 Add docs.fedoraproject.org structure for future publishing of Badges docs

Merged 5 years ago by jflory7. Opened 5 years ago by jflory7.

add/fedora-docs-fp-o into master

Add docs.fedoraproject.org structure for future publishing of Badges docs

Justin W. Flory • 5 years ago

80e4578

.gitignore

file added

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

build.sh

file added

+35

		`@@ -0,0 +1,35 @@`
		`+ #!/bin/sh`
		`+`
		`+ image="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.`
		`+ 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 faill back to docker`
		`+ # which requires root.`
		`+ if [ -f /usr/bin/podman ]; then`
		`+ runtime="podman"`
		`+ else`
		`+ runtime="docker"`
		`+ fi`
		`+ 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 $runtime to run the build in an isolated environment."`
		`+ echo ""`
		`+ $runtime run --rm -it -v $(pwd):/antora:z $image $cmd`
		`+ else`
		`+ # User isn't in the docker group; run the command with sudo.`
		`+ 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 $runtime run --rm -it -v $(pwd):/antora:z $image $cmd`
		`+ fi`
		`+ fi`

docs/README.md

file added

+120

		`@@ -0,0 +1,120 @@`
		`+ # Fedora Docs Template`
		`+`
		`+ This repository contains a minimal source structure for a new Fedora Docs source.`
		`+`
		`+ ## 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`
		+ ```
		`+`
		`+ ### 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:`
		`+`
		+ ```
		`+ $ 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:`
		`+`
		+ ```
		`+ ...`
		`+ - url: https://pagure.io/fedora-docs/modularity.git`
		`+ branches:`
		`+ - master`
		`+ ...`
		+ ```
		`+`
		`+ And replaced it with a pointer to my fork:`
		+ ```
		`+ ...`
		`+ - 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.
		`+`
		+ ```
		`+ ...`
		`+ - url: ./repositories/modularity`
		`+ branches:`
		`+ - HEAD`
		`+ ...`
		+ ```
		`+`
		+ To build the whole site, I would run the following in the `docs-fp-o` directory.
		`+`
		+ ```
		`+ $ ./build.sh && ./preview.sh`
		+ ```
		`+`

docs/antora.yml

file added

+16

		`@@ -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: badges`
		`+`
		`+ # Title will be visible on the page.`
		`+ title: Fedora Badges`
		`+`
		`+ # 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`

docs/modules/ROOT/assets/images/README.md

file added

		`@@ -0,0 +1,4 @@`
		`+ Images`
		`+ ======`
		`+`
		`+ Add static images used across documents in this directory.`

docs/modules/ROOT/nav.adoc

file added

		`@@ -0,0 +1,2 @@`
		`+ * Design assets (coming soon)`
		`+ * How-to guides (coming soon)`

docs/modules/ROOT/pages/index.adoc

file added

		`@@ -0,0 +1,4 @@`
		`+ = Fedora Badges`
		`+`
		`+ Coming soon: Fedora Badges documentation!`
		`+`

nginx.conf

file added

+14

		`@@ -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;`
		`+ }`
		`+ }`

preview.sh

file added

+36

		`@@ -0,0 +1,36 @@`
		`+ #!/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.`
		`+ # Check whether podman is available, else faill back to docker`
		`+ # which requires root.`
		`+ if [ -f /usr/bin/podman ]; then`
		`+ runtime="podman"`
		`+ else`
		`+ runtime="docker"`
		`+ fi`
		`+ 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 $runtime to run the build in an isolated environment."`
		`+ echo "The preview will be available at http://localhost:8080/"`
		`+ echo ""`
		`+ $runtime 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.`
		`+ 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 ""`
		`+ echo "The preview will be available at http://localhost:8080/"`
		`+ echo ""`
		`+ sudo $runtime 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`

site.yml

file added

+21

		`@@ -0,0 +1,21 @@`
		`+ site:`
		`+ title: Local Preview`
		`+ start_page: badges::index`
		`+ content:`
		`+ sources:`
		`+ - url: .`
		`+ branches: HEAD`
		`+ start_path: docs`
		`+ 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`

jflory7 commented 5 years ago

This pull request adds Fedora Docs support for Badges in our Pagure repository. The long-term goal is to replace the old Trac documentation with new pages about Fedora Badges (maybe in the future replacing badges.fp.o/about?), providing easy access to the design assets and resources, and a step-by-step guide on how to design a badge (probably based off Flock workshop content).

Could a member of the Docs team also take a look at this pull request and verify it's correct? I was able to generate a preview locally, but it would be nice to have external confirmation too.

rebased onto 80e4578

5 years ago