###### tags: `Documentation`

# Controller docs on access.redhat

`access.redhat` refers to the Red Hat customer portal, the canonical home for Red Hat documentation.

The downstream publishing toolchain plays nice with asciidoc content, not RST. I've been working with TVo on a conversion that makes the Controller docs that available on both [docs.ansible.com/automation](https://docs.ansible.com/automation.html) and `access.redhat`.

### Controller docs playbook

``controller_docs.yaml``

1. Clone the `ansible/product-docs` repository.
2. Delete the `sync/controller-docs` directory in the `aap-docs` repository. This makes sure the target directory is "clean" at the start of each conversion run.
3. Synchronize content from `ansible/product-docs` to the target directory. Use synchronize because we want to preserve the directory structure from `product-docs`.
4. Copy YAML examples to the repository. This is a hack that needs a better solution. The Controller RST references the YAML file directly because Sphinx allows downloadable content. In the converted ADOC the only option is an href to the raw YAML.
5. Remove the `product-docs` directory after synchronizing the content.
6. Find all the RST files in the target directory and register a variable.

The Controller docs playbook then runs several other playbooks and scripts.

### Modify RST files before conversion

``modify_controller_rst.yaml``

1. Remove metadata from the RST files because it just gets printed in the converted asciidoc.
2. Change all the includes statements for common content from relative to absolute. All ADOC files in a title need to be in the same folder. Post conversion all the common content that is converted to ADOC is copied into each title folder.

### Replace product terminology variables

``replace-controller-variables.sh``

This script replaces all the variables for product terminology in the Sphinx `conf.py` file.

This could be improved to just read all the variables from the `conf.py` and replace with their values. Otherwise any new variable in the Sphinx `conf.py` file needs to be manually added to this script.

### Convert RST files to asciidoc

``convert_rst.yaml``

Use [pandoc](https://pandoc.org/) to convert every RST file to an ADOC file then delete all the RST files.

Pandoc is a "Swiss knife" utility for converting between markup formats. It is well maintained and available under the GPL.

### Modify ADOC files after conversion

``modify_controller_adoc.yaml``

1. Find all the ADOC files and register them to a variable.
2. Change all the image directives from relative to absolute. All images need to be in the same folder and converted content should use the `:imagesdir:` asciidoc attribute to set the path.
3. Replace all `include::<filename>.rst` statements with `include::<filename>.adoc` statements.
4. Add passthroughs for regex that gets treated as markup in the transformed DocBook. For example when ADOC is transformed to DocBook `*.txt` results in an opening `<literal>` tag that causes a mismatch and breaks XML validation.
5. Delete duplicate anchors. This should probably be cleaned up in the RST source so that anchors are unique.

### Build Controller cross-references

Sphinx does a great job at handling cross-references in a given doc set, both internal and external. Asciidoc does not do such a great job.

This is the most complex part of the conversion because the Controller doc set uses a very Sphinx implementation for cross-references.

``build_controller_xrefs.yaml``

1. Prepend the asciidoc `xref:` tag to all cross-references that begin with `ug_` and `ag_`.
2. Remove the opening backtick character from the cross-reference.
3. Append closing square brakets `[]` to any resulting `xref:ug_` or `xref:ag_` strings.
4. Remove the closing backtick character from the cross-reference.

### Replacing Controller cross-references

Asciidoc does not do as good a job at handling external cross-references as Sphinx, whether they reference a different guide in the same doc set or a different file in the same title.

Note that using cross-references between files within the same title depends on the order of inclusion in the main asciidoc assembly. Files in subsequent order can cross-reference files in preceding order but not the other way around.

To make external cross-references work in Asciidoc you need to convert them to hrefs.

This is a two-step process:

1. Replace the `xref` or other Sphinx cross-reference printed as a literal in the converted asciidoc with an asciidoc attribute.
2. Create asciidoc attributes with the correct targets for cross-references.

This script replaces broken cross-references with asciidoc attributes: ``replace-controller-xrefs.sh``

This asciidoc file maps each attribute to a base url and anchor: ``controller-xrefs.adoc``

This asciidoc file sets the base urls: ``title-links.adoc``

Note that using `title-links.adoc` means you can have downstream-only base urls. That file is not synchronized downstream. There is a unique version that resides in GitLab.