###### tags: `Documentation` # Ansible SDK documentation publishing toolchain `docs.ansible.com` should be the canonical home for Ansible technical content. This reduces fragmentation of the Ansible content set, aids discoverability, and offers a cohesive user experience. This also puts the SDK docs on a clear path downstream that feeds back into the community. - Engineering teams are the primary owners of the doc set. Documentation is an engineering function. - Projects should be able to use whatever tools they like, including Sphinx and RTD. - Community docs should be portable and provide a single-source for downstream content. - Clear pathways lead to better docs. Better docs mean you can focus more on writing code. ## Public web servers The community engineering team, under Yanis Guenane, provides and maintains web servers on AWS. This already exists today for `docs.ansible.com`. We need less AWS instances, not more. Yes, but we need infrastructure to provide a cohesive experience (an Ansible "brand") that lowers barrier to entry. This allows the entire Ansible ecosystem to move forward in an organized manner and scale out and up. On the security side we use an SSH key bound to a `docs-bot` service account. The `docs-bot` account will have minimal privileges on the web server. ## GitHub action Proposal to use a github action for publishing Ansible SDK documentation to: ``` docs.ansible.com/ansible-sdk/ ``` Benefits: - Everything exists in GitHub and visible to the Ansible community. - Automatically refreshes docs on commit. - Project team owns and maintains RTD config. Community team owns and maintains the secrets for the action. Requires the following action secrets in the repo: - `SSH_KEY_DOCS` private key for `docs-bot` service account - `KNOWN_HOSTS_DOCS` known_hosts file - `SSH_USER_DOCS` SSH user name - `SSH_HOST_DOCS` SSH hostname Here is a link to the PR that adds the action: https://github.com/ansible/ansible-sdk/pull/52 ## Jenkins An alternative **and least preferred** approach to the github action is a Jenkins DSL job that clones the repo and pushes to `docs.ansible.com/ansible-sdk/`. This centralizes the private key and other sensitive bits in Jenkins config behind the VPN. The downside is that it puts everything behind the VPN so it is not visible to the Ansible community. ## Versioning strategy - `main` always syncs to `ansible-sdk/latest` - Branches for release versions sync to `ansible-sdk/<branch>` - Branches for release versions are de-indexed for SEO purposes `find . -regex "\./docs/build/html/.*html$" -exec sed -i -e "s|^<head>$|<head><meta name=\"robots\" content=\"noindex\">|" {} \;`