Quick Start ​

Overview ​

This guide provides a structured approach to documentation development, covering three primary tasks: adding, modifying, and deleting documents.

Required Skills:

• Knowledge of the openEuler documentation structure
• Proficiency in Markdown writing specifications

Standard Workflow ​

Begin by determining the repository where the target document resides. Use the manual name to find the relevant repository and directory path. Below is a step-by-step workflow for document operations, illustrated using modifications to the Installation Guide for server environments.

1. Clone the repository.

   Fork the remote repository, clone it locally, and establish an upstream connection.

   bash

   git clone https://gitee.com/wu-donger/docs.git
   git remote add upstream https://gitee.com/openeuler/docs.git

2. Switch to the target branch.

   Select the appropriate version branch (typically named stable2-<version>). For version 25.03:

   bash

   git fetch upstream
   git checkout stable2-25.03
   git rebase upstream/stable2-25.03
   git checkout -b work25.03

3. Commit changes.

   Apply changes following the dedicated sections for adding, editing, or removing documents.

   bash

   git add .
   git commit -m "Brief description of changes"

4. Push changes to the remote repository and create a pull request (PR).

   Push changes and initiate a pull request:

   bash

   git push origin work25.03

Adding Documents ​

This section guides developers through adding complete manuals. To add content to existing manuals (such as adding a "Common Tools" chapter to the Upgrade Guide), refer to Editing Documents.

The following example demonstrates adding an Upgrade Guide for server environments:

1. Create a storage directory.

   Identify the scenario for your Upgrade Guide and locate its storage path. Create a new folder to store all .md files for this guide:

   text

   ├─docs
   |  ├─en
   |  └─zh
   |    └─Server                                                       # Scenario: Server
   |       └─InstallationUpgrade                                       # First-level directory: Installation and Upgrade
   |           ├─Installation                                          # Manual: Installation Guide
   |           └─Upgrade                                               # New folder: Upgrade Guide
   |               ├─openEuler_22.03_LTS_upgrade_and_downgrade.md      # Content file
   |               └─_toc.yaml                                         # Table of contents file

2. Edit _toc.yaml.

   Create a _toc.yaml file in your new directory to maintain chapter display logic:

   yaml

   label: Upgrade Guide                                                # Manual: Upgrade Guide
   isManual: true                                                # Identifies this as a manual TOC file
   description: Upgrade the openEuler OS.                           # Manual description
   sections: 
     - label: Upgrade and Downgrade Guide                                          # Chapter: Upgrade and Downgrade Guide
       href: ./openEuler_22.03_LTS_upgrade_and_downgrade.md      # Content file reference

3. Link the manual to the scenario.

   Add a reference to your Upgrade Guide in the Server scenario's _toc.yaml:

   yaml

   label: Server                                                   # Scenario: Server
   sections:
     - label: Start Here                                           # First-level directory: Start Here
       sections:
         - href: ./releasenotes/releasenotes/_toc.yaml            # Manual: Release Notes
         - href: ./quickstart/quickstart/_toc.yaml                # Manual: Quick Start
     - label: Installation and Upgrade                                             # First-level directory: Installation and Upgrade
       sections:
         - href: ./installation_upgrade/installation/_toc.yaml    # Manual: Installation Guide

Editing Documents ​

Document modifications fall into three categories:

• Content-only changes: Modify existing manual content without altering the TOC structure. For example, adding a new installation method to the "Installation Methods" chapter of the Installation Guide.

• Adding/removing chapters: Create or delete content files and update _toc.yaml of the manual.

  Example: to add a "Common Upgrade Tools" chapter to the Upgrade Guide, first create software.md in the Upgrade Guide directory, then update _toc.yaml to reference software.md.

  yaml

  label: Upgrade Guide                                               # Manual: Upgrade Guide
  isManual: true                                               # Identifies this as a manual TOC file
  description: Upgrade the openEuler OS                          # Manual description
  sections:
    - label: Upgrade and Downgrade Guide                                         # Chapter: Upgrade and Downgrade Guide
      href: ./openEuler_22.03_LTS_upgrade_and_downgrade.md     # Content file path
    - label: Common Upgrade Tools                                       # New chapter: Common Upgrade Tools
      href: ./software.md                                      # New content file path

• Manual display position changes: Modify the scenario _toc.yaml file to adjust manual ordering.

  Example: To move the Upgrade Guide above the Installation Guide in the server scenario, edit _toc.yaml.

  yaml

  label: Server                                                      # Scenario: Server
  sections:
    - label: Start Here                                              # First-level directory: Start Here
      sections:
        - href: ./releasenotes/releasenotes/_toc.yaml               # Manual: Release Notes
        - href: ./quickstart/quickstart/_toc.yaml                   # Manual: Quick Start
    - label: 'Installation and Upgrade'                                              # First-level directory: Installation and Upgrade
      sections:
        - href: ./installation_upgrade/upgrade/_toc.yaml'           # Upgrade Guide now appears first
        - href: ./installation_upgrade/installation/_toc.yaml'      # Manual: Installation Guide
        - href: ./installation_upgrade/upgrade/_toc.yaml'
    - label: 'System Administration'
      sections:
        - href: './administration/administrator/_toc.yaml'
        - href: './administration/sysmaster/_toc.yaml'
        - href: './administration/compa_command/_toc.yaml'

Removing Documents ​

This section guides complete manual removal. To remove content from existing manuals (such as deleting the "Process Management" chapter from the Administrator Guide), refer to Editing Documents.

Example workflow for removing the Virtualization User Guide from the virtualization scenario:

1. Locate and delete the manual directory at the storage location.

2. Remove the manual reference from the virtualization scenario _toc.yaml file.

   yaml

   label: Virtualization                                                          # Scenario: Virtualization
   sections:
     - label: Virtualization Platforms                                                  # First-level directory: Virtualization Platforms
       sections:
         - href: ./virtualization_platform/virtualization/_toc.yaml      # Removed reference to the Virtualization User Guide
         - href: ./virtualization_platform/stratovirt/_toc.yaml

Temporary Documentation Storage ​

For documentation not yet ready for publication (under development or not mature enough for promotion), store files in the archive directory. These documents must still follow writing conventions and can be moved to appropriate directories when ready for publication.

Note: Documents submitted to the archive directory are scheduled for future publication. Unmaintained documents will be purged.