###### tags: `Documentation`

# Ansible docsite POC

This document has details for a proof-of-concept (POC) Ansible docsite that extends `docs.ansible.com`. The end goal of the POC is:

- Create a cohesive user experience for the Ansible community that helps drive adoption and lowers barrier to entry.
- Provides long-term, sustainable docsite tooling

## Docsite requirements

- Static site generation
- Include pull request preview capabilities for individual projects
- Provide full text, reliable seach without tracking
- Can detect 404s and declare redirects as needed
- Ability to deploy to production as part of project CI
- Be inclusive of users of assistive technology
- Allow banners for event details like Fest

## Infrastructure

The POC should include an evaluation of public-facing web servers versus static hosting (object storage).

- ec2 instance
- s3 bucket
- DNS entry for `poc.ansible.com`

## POC entries

The POC should use Ansible Lint (MD) and Ansible SDK (RST) source repositories.

- https://github.com/ansible/ansible-lint/tree/main/docs
- https://github.com/ansible/ansible-sdk/tree/main/docs

### TOX and Sphinx build

@oranod

This entry will evaluate using a GH Action vs a Jenkins DSL job to build and publish the docsite and project docs.

### Read the docs

@oranod

Work with the RTD community and investigate this option. Maybe in-house tooling is not the best option. Why not do some kind of DNS magic for projects that just want to use RTD?

Is there a hybrid option where projects use RTD and push a build to the docsite for each release?

https://github.com/readthedocs/readthedocs.org/issues/new/choose

### Astro

@oranod

This entry will evaluate using [Astro](https://astro.build/) to build and publish the docsite and project docs.

### Docusaurus

@ssbarnea

https://docusaurus.io/

### Lektor

https://www.getlektor.com/

# External resources

* [Recent comparison between sphixn, mkdocs and others](https://github.com/frequenz-floss/frequenz-sdk-python/issues/53#issuecomment-1293556506)
*