From 2d9759b4c24ac4596fee41144ff24e981d89c8a8 Mon Sep 17 00:00:00 2001 From: David Kaufmann Date: Aug 02 2024 03:09:15 +0000 Subject: [PATCH 1/2] typographical changes --- diff --git a/wg/modules/ROOT/pages/usr-docs-maintenance/local-authoring.adoc b/wg/modules/ROOT/pages/usr-docs-maintenance/local-authoring.adoc index 05f3766..62d8b54 100644 --- a/wg/modules/ROOT/pages/usr-docs-maintenance/local-authoring.adoc +++ b/wg/modules/ROOT/pages/usr-docs-maintenance/local-authoring.adoc @@ -1,26 +1,26 @@ -= Setting up a local authoring envireonment += Setting up a local authoring environment The Fedora Server Edition working group; Peter Boy (pboy); Stephen Daley (mowest) :page-authors: {author}, {author_2}, {author_3} // :revnumber: F37-F38 :revdate: 2023-04-23 -Fedora Server documentation is at: https://pagure.io/fedora-server/. +Fedora Server documentation is at: https://pagure.io/fedora-server/. -It includes the content as well as various scripts to build and preview the site locally. The directory structure is predefined by the docs Content Management System (Andorra) and must not be changed. +It includes the content as well as various scripts to build and preview the site locally. The directory structure is predefined by the docs Content Management System (Andorra) and must not be changed. -It has 2 permanent branches: „main“ for the published content and „stg“ for planning, development, and discussion. Temporarily, additional branches may also be present. +It has 2 permanent branches: "main" for the published content and "stg" for planning, development, and discussion. Temporarily, additional branches may also be present. For up- and download you can use either https or ssh. For people with FAS account ssh may be more convenient. -The workflow folllow the Fedora docs project „[https://docs.fedoraproject.org/en-US/fedora-docs/contributing/git/ Git for docs writers]“. Each contributor should create a fork of the repository for themselves. Contributions are uploaded to the fork and then transferred to the authoritative version via a pull request. This opens up the possibility for others to comment and initiate a broader discussion. +The workflow folllow the Fedora docs project "[https://docs.fedoraproject.org/en-US/fedora-docs/contributing/git/ Git for docs writers]". Each contributor should create a fork of the repository for themselves. Contributions are uploaded to the fork and then transferred to the authoritative version via a pull request. This opens up the possibility for others to comment and initiate a broader discussion. -=== Writing tools +== Writing tools -You can use any ASCII editor to work on the documentation files. +You can use any ASCII editor to work on the documentation files. -A particularly useful OSS Asciidoc editor is https://asciidocfx.com[AsciidocFX]. It is a Java program, very easy to install, and provides both an integrated directory access, a toolbar with the most common AsciiDoc formatting similar to a Word editor and an integrated instant preview. +A particularly useful OSS Asciidoc editor is https://asciidocfx.com[AsciidocFX]. It is a Java program, very easy to install, and provides both an integrated directory access, a toolbar with the most common AsciiDoc formatting similar to a Word editor and an integrated instant preview. -=== Creating a new documentation article +== Creating a new documentation article An xref:attachment$srv-template.adoc[annotated template] is available to make things easier. Download it and save it in the appropriate directory with a new name. @@ -43,22 +43,22 @@ All file names are in lower case. == Preparations -1. *Create a local subdirectory* where the files of the documentation should be stored, and make it to your default. We use fedora-server-docs in your home throughout this guide -+ - […]$ mkdir ~/fedora-server-docs - […]$ cd ~/fedora-server-docs - - 2. Still in your default working directory, *clone fedora-server* repository - + - […]$ git clone https://git@pagure.io/fedora-server.git -o upstream - + - Git will copy the complete server repo including all branches, specifically „main“ and „stg“ mentioned above, into a local repo on your local workstation (into _.git/_ located in your default directory). - + - Git does „tag“ the cloned repo as remote repo „*upstream*“. - + - At the same time it checks out the default branch „''main''“ into your ''working directory'' (i.e. ~/fedora-server-docs in the above example). Therefore, when the operation terminates, you will find in your current default directory, which is now your ''working directory'', some files, e.g. README.md, build.sh and preview.sh and a directory docs. The latter contains the content. - + - If you leave off „./“ at the end, git creates another directory in your default directory with the name of the repository, i.e. fedora-server. And this directory is then the "_working directory_" to the repository. This can be useful if you want to keep track of different fedora docs projects in one directory. +1. *Create a local subdirectory* where the files of the documentation should be stored, and make it your default. We use fedora-server-docs in your home directory throughout this guide ++ + […]$ mkdir ~/fedora-server-docs + […]$ cd ~/fedora-server-docs + +2. Still in your default working directory, *clone fedora-server* repository ++ + […]$ git clone https://git@pagure.io/fedora-server.git -o upstream ++ +Git will copy the complete server repo including all branches, specifically "main" and "stg" mentioned above, into a local repo on your local workstation (into _.git/_ located in your default directory). ++ +Git does "tag" the cloned repo as remote repo "*upstream*". ++ +At the same time it checks out the default branch "''main''" into your ''working directory'' (i.e. ~/fedora-server-docs in the above example). Therefore, when the operation terminates, you will find in your current default directory, which is now your ''working directory'', some files, e.g. README.md, docsbuilder.sh and preview.sh and a directory docs. The latter contains the content. ++ +If you leave off "./" at the end, git creates another directory in your default directory with the name of the repository, i.e. fedora-server. And this directory is then the "_working directory_" to the repository. This can be useful if you want to keep track of different fedora docs projects in one directory. 3. In your browser go to https://pagure.io/fedora-server/, log in and *create a Fork*. Once you have done it, the button will read _View fork_. Switch to your fork and click on Clone and you will see 2 addresses you can use to clone (copy) the content to your local default directory + @@ -79,19 +79,19 @@ You can use https as well. For users with a FAS account ssh is usually the bette upstream https://git@pagure.io/fedora-server.git (fetch) upstream https://git@pagure.io/fedora-server.git (push) + -In your workflow you will update your local version to the latest versions of the server repository by „pulling“ the content from „upstream“ and upload your modifications and additions by „pushing“ it to origin, i.e. to your fork. You will than create a „pull requuest“, i.e. pick up your modifications and additions from your fork and integrate it into the generic repository („origin“). This enables co-writers to review our work and comment on it. +In your workflow you will update your local version to the latest versions of the server repository by "pulling" the content from "upstream" and upload your modifications and additions by "pushing" it to origin, i.e. to your fork. You will than create a "pull request", i.e. pick up your modifications and additions from your fork and integrate it into the generic repository ("origin"). This enables co-writers to review our work and comment on it. -5. In your working directory create the *built und preview* +5. In your working directory build the local version and start the preview tool. + - […]$ ./build.sh && ./preview.sh - -6, Back to your browser enter the *local preview address*': _localhost:8080_ -* -You should see a local preview of the current Server documentation + […]$ ./docsbuilder.sh -=== Working on content === +6. Back in your browser enter the *local preview address*': _localhost:8080_ ++ +* You should see a local preview of the current Server documentation + +== Working on content -1. Check, if you are on the branch to intend to work on +1. Check if you are on the branch you intend to work on + […]$ git branch main @@ -104,21 +104,23 @@ You should see a local preview of the current Server documentation Git will adjust and modify the content of your working directory accordingly! 3. Before your begin to work update your working directory - […]$ git commit -m „“ - ++ + […]$ git commit -m "" + 4. Modify content 5. Update preview and check: - […]$ ./build.sh && ./preview.sh ++ + […]$ ./docsbuilder.sh + Preview in your browser using the address _'localhost:8080_ -6. Repeat step 4 & 5 as required. +6. Repeat step 4 & 5 as required. -=== Save Your Work +== Save Your Work -Commit your work locally and then push it into your fork „_origin_“. +Commit your work locally and then push it into your fork "_origin_". 1. Check status + @@ -129,12 +131,11 @@ Commit your work locally and then push it into your fork „_origin_“. […]$ git add 3. Commit locally - […]$ git commit -m „“ - -4. Transfer to your fork of fedora server repository + - […]$ git push origin [main|stg] - -5. In your browser open https://pagure.io/fedora-server, login, switch to your fork, and create a pull request. + […]$ git commit -m "" +4. Transfer your fork of fedora server to the repository ++ + […]$ git push origin [main|stg] +5. In your browser open https://pagure.io/fedora-server, login, switch to your fork and create a pull request. From 6b95918bb9df4b8803a5605ac6b0600385b9668c Mon Sep 17 00:00:00 2001 From: David Kaufmann Date: Aug 02 2024 03:11:09 +0000 Subject: [PATCH 2/2] wrong filename, missed one occurrence --- diff --git a/README.md b/README.md index 2107c18..7b64cbc 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ Note: Replace master with main on all occations on above document: To build and preview docs, run: ``` -$ ./build.sh && ./preview.sh +$ ./docsbuilder.sh ``` The result will be available at http://localhost:8080