###### tags: `Documentation` # Docs tooling request: Ansible API reference content This document outlines the need for publishing tooling for `access.redhat` to handle API reference content that is generated from source code. ## Controller API Ansible Automation Platform Controller provides a RESTful API that allows programmatic access for Red Hat customers. The documentation set includes an API reference that is built from source. Specifically the API reference is Swagger content that is built as a release artifact with a github action. **Need:** A workflow that allows the Controller docs team can to hand over Swagger content that gets published to the Red Hat customer portal. The ideal workflow is as follows: 1. Controller docs team generates FINAL version of Swagger content. 2. Controller docs team uploads Swagger content (`swagger.json`) and release configuration. 3. Customer portal tooling plugs content into Red Hat flavoured Swagger UI assets. https://docs.ansible.com/automation-controller/latest/html/controllerapi/api_ref.html ## Ansible SDK Ansible SDK provides application developers with a programmatic automation toolkit. Red Hat customers can perform automation runs as part of their business logic. The Ansible SDK API exposes classes in a public `ansible_sdk.*` namespace. The objects, functions, and attributes in those classes include documentation as Python docstrings. The Ansible SDK engineering team are the primary authors of this content, which is of critical need to Ansible SDK users. Sphinx tooling automatically generates HTML content from the docstrings with an intermediate transformation to RST. **Need:** A workflow that allows the Ansible SDK team to hand over generated HTML, or RST, that gets published to the Red Hat customer portal. The ideal workflow is as follows: 1. SDK team generates FINAL version of API reference content. 2. SDK team uploads API reference content and release configuration. 3. Customer portal hosts the generated HTML. ## Concerns and wishlist stuff - Consistent look and feel. Can the DXP team provide some assets for generated HTML, perhaps a Red Hat theme for Sphinx projects? - SEO. Canonical homes, version indexing, la la la - Integration with CCS source content. Developers naturally write more reference content (programmatic options and expected behaviour). Tech writers go for more concepts and procedures. Tooling should allow intuitive source combinations that increase team velocity and improve technical accuracy.