How to create and use a local Fedora authoring environment

In a local environment, you can create or edit your documents offline, without an Internet connection; using a local git repository containing a complete set of documents and tools to edit and preview them in a local build of Docs pages. It is by far the most flexible way of working with Docs repositories, enabled by the extensive adaptation to individual work routines and work equipment.

A local writing environment allows full access to all the resources you routinely use on your workstation and is therefore perfectly adaptable to your style of working. It is particularly suitable for the creation of a completely new set of documentation on a topic or for revision of an existing set of documentation.

Prerequisites

  1. You need to fullfill the basic requirements as specified in Write contributions to Docs.

  2. You need to install various tools, specifically git, a container providing the instrumentation to convert the AsciiDoc files and a minimal web server to display them. This is described in Setting up a local working environment.

  3. The system uses CLI tools in most steps of the process. Having some experience working in the Linux Terminal is therefore necessary or must be learned in parallel.

How to work in a local Fedora authoring environment

The following instructions provide a short, step-by-step guide for setting up your own environment:

Preparations

If you want to start working on Documentation you haven’t worked on before, follow the below steps to set up a local authoring environment:

  1. Change to the base directory of your documentation project.

    […]$ cd ~/<my-doc-project>
  2. Update your local data

    […]$ git pull

Work on content

  1. List the branches and check if you are on the branch you intend to work on

    […]$ git branch
    * main
    stg

    Usually you see a main branch (sometimes named "master") and one or more project specific branches. Many projects have a "staging" (stg) branch among others to facilitate a preview for a broader audience. A "*" symbol marks the currently active branch.

    Switch to the branch as necessary

    […]$ git checkout <your_branch>
  2. Use the editor of your choice to modify the content. Keep your default directory as is and load the necessary file(s) into the editor.

  3. Update preview and check

    […]$ ./build.sh && ./preview.sh

    Preview in your browser using the address localhost:8080

  4. Repeat step 2 & 3 as required.

Save your work

  1. Check git status

    […]$ git status
    On branch stg
    Your branch is up to date with 'upstream/stg'.
    
    Changes to be committed:
      (use "git restore --staged <file>..." removes a file from the staging area, but any modifications to the file are untouched)
    	modified:   modules/ROOT/nav.adoc
    	modified:   modules/ROOT/pages/contributing-docs/asciidoc-intro.adoc
    
    Changes not staged for commit:
      (use "git add/rm <file>..." to update what will be committed)
      (use "git restore <file>..." to discard changes in the working directory)
    	modified:   modules/ROOT/pages/contributing-docs/asciidoc-markup.adoc
    	modified:   modules/ROOT/pages/...
    	modified:   modules/ROOT/pages/...
    
    Untracked files:
      (use "git add <file>..." to specify which files will be committed)
    	modules/ROOT/pages/contributing-docs/contrib-new-documentation.adoc
    	modules/ROOT/pages/...
    	modules/ROOT/pages/...

    You then receive the following list of files: "ready to be committed" files and "modified" files. Occasionally there may also be "untagged" files.

  2. As advised in the output, use git add to add each file one by one to the "ready to be committed" files or use git add -v to add all files in one go. Please note that it is best to create small commits that combine related files for a problem domain.

    […]$ git status add modules/ROOT/pages/contributing-docs/asciidoc-markup.adoc
    […]$ git status add modules/ROOT/pages/...
    […]$ git status add modules/ROOT/pages/...
  3. Commit your work locally. Please choose a commit comment that is as short as possible, but also meaningful to other people who may view your code.

    […]$ git commit -m „<YOUR COMMIT MESSAGE>“
  4. Transfer your work to YOUR fork of the repository. If you don’t specify a branch, git uses the current one.

    […]$ git push origin [<branch>]
  5. Within your browser, open the repository and switch to your fork. Then create a pull request.

  6. Done. Repeat steps 2 - 4 as needed.