Creating a new guide - RedHatInsights/red-hat-ansible-automation-platform-documentation GitHub Wiki

Creating a new guide

This checklist helps you remember the files, directories, and symbolic links you need to set up when you are adding a new guide to the docset.

Create directories in the repo:

  • ❏ Create a directory for the main book: /titles/aap-on-azure

  • ❏ Create a directory for the assemblies: /assemblies/aap-on-azure

  • ❏ Create a directory for the modules: /modules-aap-on-azure

Create symlinks so that it’s easy to include modules and assemblies in a book. Use tab autocompletion to get the right path for your symlinks.

  • ❏ In /titles/aap-on-azure, create a symlink to the assembly directory (/assemblies/aap-on-azure)

  • ❏ in /titles/aap-on-azure, create a symlink to the attributes directory (/attributes)

  • ❏ in /titles/aap-on-azure, create a symlink to the images directory (~/<path_to_your_repo>/downstream/images)

  • ❏ in /titles/aap-on-azure, create a symlink to the aap-common directory (~/<path_to_your_repo>/aap-common)

The AAP on Azure doc uses new directories for assemblies and modules. Add a symbolic link in the new assemblies directory to point to the modules directory.

  • ❏ In /assemblies/aap-on-azure, create a symlink to the modules directory (/modules/aap-on-azure)

Add content:

  • ❏ Add new Ansible on Azure aliases to /attributes/attributes.adoc

  • ❏ Create titles/aap-on-azure/master.adoc

  • ❏ Create titles/aap-on-azure/docinfo.xml

  • ❏ Create an assembly and a couple of modules. You can use newdoc to generate pre-populated module and assembly files formatted with AsciiDoc. Use the include statement to include them in the guide.

Example of adding symlinks for the AAP on Azure doc:

# Navigate to `titles/aap-on-azure`. 
# Create symlinks to the `/assemblies`, `/attributes, `/common`, and `/images` directories : 
$ ln -s ../../assemblies/aap-on-azure ./aap-on-azure
$ ln -s ../../attributes ./attributes
$ ln -s ../../images ./images
$ ln -s ../../../aap-common ./aap-common

# Navigate to assemblies/aap-on-azure. Create a symlink to the modules directory for AAP on Azure:
$ ln -s ../../modules/aap-on-azure ./aap-on-azure

The title/aap-on-azure directory structure after these changes:

➜  /titles/aap-on-azure/
$ tree -l .
.
β”œβ”€β”€ aap-on-azure -> ../../assemblies/aap-on-azure
β”‚   β”œβ”€β”€ aap-on-azure -> ../../modules/aap-on-azure
β”‚   β”‚   β”œβ”€β”€ con-about-aap-on-azure.adoc
β”‚   β”‚   └── con-why-aap-on-azure.adoc
β”‚   └── assembly-intro-to-aap-on-azure.adoc
β”œβ”€β”€ attributes -> ../../attributes
β”‚   └── attributes.adoc
β”œβ”€β”€ aap-common -> ../../../aap-common
β”‚   └── making-open-source-more-inclusive.adoc
β”œβ”€β”€ docinfo.xml
└── master.adoc
β”œβ”€β”€ images -> ../../images
β”‚   β”œβ”€β”€ aap-on-azure-architecture.png
β”‚   β”œβ”€β”€ <# Snipped list of image files for clarity>
β”‚   └── security-lab-environment.png

Example of adding symlinks for the High Availability doc:

The High Availability doc uses assemblies and modules from the pre-existing assemblies/hub and modules/automation-hub directories. This means that you do not need to add a symlink in the assemblies directory to point to the modules directory.

Note that the High Availability title directory (/titles/hub/high-availability/) is at a deeper nested level than the AAP on Azure title (titles/aap-on-azure/). The paths in the symlinks are therefore different. Use tab autocompletion to get the right path for your symlinks.

# Navigate to the `/titles/hub/high-availability/` directory. 
# Create symlinks to the `/assemblies`, `/attributes` `/common`, and `/images` directories : 
$ ln -s ../../../assemblies/hub ./hub
$ ln -s ../../../attributes ./attributes
$ ln -s ../../../images ./images
$ ln -s ../../../../aap-common ./aap-common

Example PR: Creating the Ansible on Azure guide

Note that this guide was created before the common directory was added to the repo.

  • PR#222 creates the new files, symlinks, and directories

  • AAP-1668 is the Jira issue for this work.

⚠️ **GitHub.com Fallback** ⚠️