diff --git a/README.md b/README.md index fab57ed..1416799 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,4 @@ -# Fedora Docs Template - -This repository contains a minimal source structure for a new Fedora Docs source. - -## Structure - -``` -|-- README.md -|-- antora.yml ....................... 1. -|-- docsbuilder.sh ................... 2. -|-- nginx.conf ....................... 3. -|-- site.yml ......................... 4. -`-- modules - `-- ROOT ......................... 5. - |-- assets - | `-- images ............... 6. - | `-- * - |-- nav.adoc ................. 7. - `-- pages .................... 8. - `-- *.adoc -``` - -1. Metadata definition. -2. A script that does a local build. It shows a preview of the site in a web browser by running a local web server. Uses podman or Docker. -3. A configuration file used by the local preview web server. -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 Modularity. -* **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. +# Fedora Forge Documentation ## Local preview diff --git a/antora.yml b/antora.yml index 0b0237f..75faedf 100644 --- a/antora.yml +++ b/antora.yml @@ -2,10 +2,10 @@ # 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 +name: forge-documentation # Title will be visible on the page. -title: Pizza Factory # <---- PLEASE MODIFY +title: Fedora Forge Documentation # 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. diff --git a/modules/ROOT/assets/images/pizza.png b/modules/ROOT/assets/images/pizza.png deleted file mode 100644 index bdecba7..0000000 Binary files a/modules/ROOT/assets/images/pizza.png and /dev/null differ diff --git a/modules/ROOT/examples/exampe-example.adoc b/modules/ROOT/examples/exampe-example.adoc deleted file mode 100644 index fa408e4..0000000 --- a/modules/ROOT/examples/exampe-example.adoc +++ /dev/null @@ -1,9 +0,0 @@ -This is an example of a example file. Unlike files in `pages/`, files in this directory are not built as standalone pages, but only if they are included in a file within `pages/`. Also unlike examples, -A file in this directory can be included within any file in the `pages/` directory. - -Most common use cases for examples is using output from an external script (for example, translation string statistics) in docs. You can use an external script to update the example, and when the site is rebuilt, it will show updated output. - -If you want to include this particular example somewhere, you can use the following syntax: `include::example$example-example.adoc[]`. -Note the use of `example$` instead of an actual file location. - -See link:https://docs.antora.org/antora/3.0/examples-directory/[Antora docs on examples] for more information about partials. diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 0cefda4..56d95e1 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -1,5 +1,4 @@ -* xref:architecture.adoc[Architecture] -** xref:pizza-oven.adoc[Pizza Oven] -** xref:pizza-dough.adoc[Pizza Dough] -* xref:community.adoc[Community] -* xref:faq.adoc[FAQ] +* xref:user_docs.adoc[User Documentation] +// ** xref:pizza-oven.adoc[Pizza Oven] +// ** xref:pizza-dough.adoc[Pizza Dough] +* xref:admin_docs.adoc[Admin Documentation] diff --git a/modules/ROOT/pages/admin_docs.adoc b/modules/ROOT/pages/admin_docs.adoc new file mode 100644 index 0000000..6a4f9a5 --- /dev/null +++ b/modules/ROOT/pages/admin_docs.adoc @@ -0,0 +1,3 @@ += Admin Documentation + +Admin Docs \ No newline at end of file diff --git a/modules/ROOT/pages/architecture.adoc b/modules/ROOT/pages/architecture.adoc deleted file mode 100644 index 0c0ba47..0000000 --- a/modules/ROOT/pages/architecture.adoc +++ /dev/null @@ -1,3 +0,0 @@ -= 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-oven.adoc[pizza oven]. This way, we can achieve a mediocre 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 deleted file mode 100644 index def9977..0000000 --- a/modules/ROOT/pages/community.adoc +++ /dev/null @@ -1,3 +0,0 @@ -= 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 deleted file mode 100644 index 32a9d51..0000000 --- a/modules/ROOT/pages/faq.adoc +++ /dev/null @@ -1,7 +0,0 @@ -= 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 straightforward. 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 9219ee9..7525896 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -1,13 +1,38 @@ include::partial$attributes.adoc[] -= The Pizza Project -John Doe; Jane Doe -:page-authors: {author}, {author_2} += Fedora Forge: Your Home for Fedora Collaboration -The Pizza Project is a useful project with a very bad name — it helps you with writing some new documentation for Fedora. +Welcome to Fedora Forge, the official home for Fedora teams, SIGs, and +subprojects. Built on the open-source Forgejo platform, Fedora Forge is a +dedicated space designed to streamline development and collaboration across the +Fedora Project. -In fact, this is just a source template for a new piece of the Fedora Docs. +This documentation serves as your comprehensive guide to Fedora-specific +workflows, as well as general-purpose workflows that are commonly used on Fedora +Forge. For more generic Forgejo workflows, such as basic Git commands, pull +requests, and issue tracking, please refer to the official +link:https://forgejo.org/docs/latest/[Forgejo Documentation]. -image::pizza.png[Pizza] +== Common Workflows and How-Tos + +Here you'll find detailed guides on the most common tasks you'll perform on +Fedora Forge: + +* *Repository Management:* Learn how to create and manage repositories, + including how to set up a custom front page for your organization. + +* *Team and User Management:* Understand how teams are managed through Fedora + Accounts groups, and how to define permissions for your contributors. + +* *CI/CD Automation:* Find out how to use the Forgejo Runner to automate your + workflows and improve your team's efficiency. + +== Known Issues and Workarounds + +We are actively working to resolve known issues to ensure a smooth experience +for all users. This section of the documentation will be kept up-to-date with +workarounds for any known bugs or limitations you might encounter. If you run +into an issue not listed here, please file a bug report against the +`forgejo-deployment` project on Fedora Forge. Last updated in {year}. diff --git a/modules/ROOT/pages/pizza-dough.adoc b/modules/ROOT/pages/pizza-dough.adoc deleted file mode 100644 index 5b59bae..0000000 --- a/modules/ROOT/pages/pizza-dough.adoc +++ /dev/null @@ -1,3 +0,0 @@ -= 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-oven.adoc b/modules/ROOT/pages/pizza-oven.adoc deleted file mode 100644 index ad460cd..0000000 --- a/modules/ROOT/pages/pizza-oven.adoc +++ /dev/null @@ -1,3 +0,0 @@ -= Pizza Oven Architecture - -Pizza oven architecture would be described on this page. Since this is just a template, I choose to disappoint you and not describe the pizza oven architecture. diff --git a/modules/ROOT/pages/user_docs.adoc b/modules/ROOT/pages/user_docs.adoc new file mode 100644 index 0000000..b61263c --- /dev/null +++ b/modules/ROOT/pages/user_docs.adoc @@ -0,0 +1,3 @@ += User Documentation + +User docs \ No newline at end of file diff --git a/modules/ROOT/partials/attributes.adoc b/modules/ROOT/partials/attributes.adoc index f5420a7..91c4e17 100644 --- a/modules/ROOT/partials/attributes.adoc +++ b/modules/ROOT/partials/attributes.adoc @@ -1 +1 @@ -:year: 2021 +:year: 2025 diff --git a/modules/ROOT/partials/partial-example.adoc b/modules/ROOT/partials/partial-example.adoc deleted file mode 100644 index 0f8f1ed..0000000 --- a/modules/ROOT/partials/partial-example.adoc +++ /dev/null @@ -1,15 +0,0 @@ -This is an example of a partial file. Unlike files in `pages/`, files in this directory are not built as standalone pages, but only if they are included in a file within `pages/`. This stops fragments of pages being built and discovered by search engines. - -A file in this directory can be included within any file in the `pages/` directory. - -Most common use cases for partials are: - -. Reusing attributes such as the current year or a release version throughout the entire module while being able to change it easily (such as changing "Fedora 33" to "Fedora 34" when a new release comes out). -. Reusing content such a banner or an infobox (`[NOTE]`, etc.) that appears on multiple pages and needs to have consistent content everywhere (such as a message on some of the quick-docs that warns the reader about their unreviewed status). - -In these cases, you can use a partial to include the same content in multiple places, and you only need to change it once to get the change to appear in every spot it's included in. You can see the first example used in `pages/index.adoc` in this repository; note the include statement on top. - -If you want to include this particular example somewhere, you can use the following syntax: `include::partial$partial-example.adoc[]`. -Note the use of `partial$` instead of an actual file location. - -See link:https://docs.antora.org/antora/3.0/partials-directory/[Antora docs on partials] for more information about partials. diff --git a/site.yml b/site.yml index 427de3b..bb8d655 100644 --- a/site.yml +++ b/site.yml @@ -1,6 +1,6 @@ site: title: Local Preview - start_page: pizza-factory::index.adoc + start_page: forge-documentation::index.adoc content: sources: - url: .