Creating a new guide

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

If your new guide won’t use an existing assemblies or modules directory, create new directories:

• ❏ 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) or /assemblies/platform

• ❏ 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)

If your new doc uses new directories for assemblies and modules, you must 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 aliases to /attributes/attributes.adoc if required.

• ❏ 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

# The AAP on Azure doc uses new assemblies and modules directories, so you need to add a symlink.
# 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.