Skip to content

Latest commit

 

History

History
123 lines (66 loc) · 4.26 KB

README.adoc

File metadata and controls

123 lines (66 loc) · 4.26 KB
Raw

Doc Kit

  • Initialize SUSE or openSUSE documentation repositories.

  • Update boilerplate files contained in documentation repositories.

What it is

Doc Kit consists of two parts:

  • a command-line tool called doc-kit that can download documentation boilerplate files

  • a repository of documentation boilerplate files, such as the SUSE book preface and entity files

Both are currently hosted in this Git repository.

Installing Doc Kit

The doc-kit command-line tool can be installed in the following ways:

  • Install it as an RPM for openSUSE from the OBS project Documentation:Tools, under the package name doc-kit. (Generally preferred.)

  • Clone this Git repository and use bin/doc-kit.

Setting up a completely new project

  1. Create a new directory and switch to it.

  2. Create a Git repository in the directory: git init.

  3. Within this directory, run doc-kit.

  4. Specify the document type you want to create. Currently, the options are docbook5-book and asciidoc-release-notes.

  5. Document types can have variants. This allows, for example, to ship a slightly different set of files for products that support a single architecture versus products that support multiple architectures.

    • If the selected type has variants, specify the ones needed in your situation.

    • If there are no variants, this step will be skipped.

  6. Doc Kit will now download all necessary files. At the end, it will create a settings file doc-kit.conf.

  7. Add and commit all downloaded files to the Git repo (including the doc-kit.conf settings file): git add . && git commit

  8. Start customizing the files:

    • Doc Kit makes a distinction between files downloaded only once during the initial setup ("initial") and files that are updateable ("always").

    • Which type of file you are looking at is noted in the first few lines of the file header.

    • Do not edit updateable files, or you will run into issues on later updates with Doc Kit. (As also noted in the file header.)

    • Do edit initial files, so they fit with your project. Feel free to remove the file headers from initial files.

  9. Make sure the edited project validates: daps -d DC-example validate

  10. Commit your changes again.

Converting a project to Doc Kit

  1. Go to your project directory.

  2. Make sure there are no uncommitted changes and no stray unstaged files in your project directory.

  3. Within this directory, run doc-kit.

  4. Specify the document type you want to create. Currently, the options are docbook5-book and docbook4-release-notes.

  5. Document types can have variants. This allows, for example, to ship a slightly different set of files for products that support a single architecture versus products that support multiple architectures.

    • If the selected type has variants, specify the ones needed in your situation.

    • If there are no variants, this step will be skipped.

  6. Doc Kit will now download all necessary files. At the end, it will create a settings file doc-kit.conf.

  7. Get an overview of the unstaged new files added by Doc Kit using git status.

  8. Start customizing the files:

    • Doc Kit makes a distinction between files downloaded only once during the initial setup ("initial") and files that are updateable ("always").

      • Do not edit updateable files, or you will run into issues on later updates with Doc Kit. (As also noted in the file header.)

      • Do edit initial files, so they fit with your project. Feel free to remove the file headers from initial files.

    • Which type of file you are looking at is noted in the first few lines of the file header.

    • Most likely, many will duplicate files that are already in your repo. If so, give preference to the new files and remove the old ones from your Git repo. Integrate necessary changes from the old files into the new ones.

    • Remove the old boilerplate files from Git

  9. Make sure the edited project validates: daps -d DC-example validate

  10. Add and commit all changes to the Git repo (including the doc-kit.conf settings file): git add . && git commit

Updating a Doc Kit project

  1. Go to the project directory.

  2. Run doc-kit.

  3. Check whether everything still builds.

  4. Commit.

Creating a kit