# Splitting Ansible 3.0.0 from Ansible Core Docs

**problem statement**

- The `ansible` PyPI package called version 3.0.0 will release in Jan/Feb 2021 timeframe and some time after that, the `ansible-core` PyPI package called version 2.11 will release. We need a way for docs to reflect the two "streams" of versions. Ansible 3.0.0 docs need to reference back to `ansible-base` 2.10 docs for all Ansible features that are not collections.

**NOTE:** Based on feedback, this proposal now suggests that docs.ansible.com/ansible is the full Ansible documentation, and `ansible-core` gets its own docsite.

***additional problems***
See https://hackmd.io/iDEyihLqRtWnjtOUd3pNYQ for a full list of problems, aka The Docs Headache Generator.

- [Splitting Ansible 3.0.0 from Ansible Core Docs](#splitting-ansible-300-from-ansible-core-docs)
* [How to do all this?](#how-to-do-all-this-)
* [Ansible Core Documentation](#ansible-core-documentation)
* [Ansible Collection Documentation](#ansible-collection-documentation)
* [How to handle /latest/](#how-to-handle--latest-)
* [TBD](#tbd)
- [Pros/Cons of this approach](#pros-cons-of-this-approach)
* [Benefits of this approach](#benefits-of-this-approach)
* [Drawbacks to this approach](#drawbacks-to-this-approach)
- [Docsite states in time](#docsite-states-in-time)
- [Publishing options](#publishing-options)
- [Older Draft Ideas](#older-draft-ideas)

<small><i><a href='http://ecotrust-canada.github.io/markdown-toc/'>Table of contents generated with markdown-toc</a></i></small>

## How to do all this?
Since we prefer that ansible/ansible document the Ansible package, the proposal is:
* Use docs.ansible.com/ansible an Ansible package docset/docsite to cover collection level information starting as 3.0.0. This includes the user guides etc from stable-2.10.
* Hack away in ansible/ansible devel to create a future Ansible Core 2.11 docset. Publish this on a new ansible-core docsite as /devel/. Have it all ready in time for the 2.11 release next Spring.
* Add banner on Ansible 4.0.0 docsite to reference Ansible Core 2.11 docsite and visa versa.

## Ansible Core Documentation
This is fundamentally most of the existing docsite without the collection index, scenario guides etc, published to a new url.

* Installing ansible-core (to be written)
* ansible-core porting guides
* Using Ansible
* ansible-builtin index (likely a makefile change)
* Appendix (minus Galaxy, tower, and AH)
* ansible-core roadmap

See http://docs.testing.ansible.com/ansible/2.11/ for a hack of what this Ansible Core docsite might look like.

## Ansible package Documentation
This a continuation of the existing docsite that will include:

* Installing Ansible (remove ansible-core install)
* Ansible porting guides
* Ansible User Guide (from stable-2.10)
* Collection scenario guides
* Network Guides
* Security Guides
* Collection index
* Other tools and references (Galaxy guides, links to Tower/AH etc)
* Ansible roadmap

See http://docs.testing.ansible.com/ansible/3.x/ for a hack of what this Ansible the package docsite might look like. This would solve the current problem where the network and scenario guides need to be tied to a collection or Ansible package release.

## How to handle /latest/
Although with docsites, each could have their own chosen release as '/latest' (once `ansible-core` 2.11 is published. See [Docsite states in time](Docsite-states-in-time), we decided to use '/latest' only on the Ansible-the-package site. From the reader perspective for Ansible users, when Ansible is latest but points to an ansible-core release which is not latest (that three weeks between core release and Ansible picking it up. To resolve this:
* Ansible will use /latest/ and hold the cannonical url definition.
* ansible-core will use only versioned urls (no latest, no cannonical).

This solves the problem of search results hitting two latest/cannonical url definitions with the same content (aka user guide).

## TBD
* Community Guide - [proposal for new docsite](https://hackmd.io/cU-o0JfvST60EoZP3KGBEg?both) for docs.ansible.com/community
* Developer Guide - can this be release-independent? or does it have to tie to a given release?
* Galaxy guides - are applicable to both and also have unique content on ansible.galaxy.com. TBD what galaxy-ng documentation needs might be.
* Should we move the Ansible Collections rst files etc to their own repo in `ansible-collections/docs` so that we can label/publish etc independent of core releases? These files are the scenario guides, network guides, etc that are currently in ansible/ansible. This would help with the independent versioning and cannonical url since those are both set in the Sphinx conf.py file. Is there any value in leaving these .rst files in the core repo? Any drawbacks to moving them?
* Where do we document 'How to be included in the Ansible package'? - Since it shouldn't need to be versioned, it could be part of the community guide.
* Dedicated themes (colors?) for the different docsites (`/ansible`, `/ansible-core`, `/community`). Colors should match the boxes on the new docs.ansible.com home page.

## Ansible.builtin plugins
Ideally we would not duplicate these, but until they are removed from core, we need them in both places because builtin updates will happen on core faster than they will in Ansible. (aka new options appear first in core).

# Pros/Cons of this approach
The guiding principle here is that the Ansible Documentation includes everything, much as it does today. The`ansible-core` documentation repeats the user guide etc but none of the collection details beyond that.

## Benefits of this approach
* Solves the versioning problem.

## Drawbacks to this approach
* Considerable duplicated content. User guide and possibly the builtin module index appears on both sites.
* Ansible documentation will be complete, but ansible-core will not, in the sense that a reader won't find all the world of collections there.
* Readers will hop between sites and the only way 'back' is the back browser button. Optionally, we could force any links from the collection docs to ansible core docs use a new browser tab (html hack). We can also add links to the banners of each site to link back to the correct version of the alternate docsite. e.g core 2.12 banner says 'this version is included as part of Ansible 4.0.0' with a link.
* Unsure what happens to /latest/ and cannonical urls between when Ansible 3.0.0 release and when `ansible-core` 2.11 releases. See [How to handle /latest/](How-to-handle-/latest/).
* Edit on GitHub for manual rst files become problematic whilst we are hacking away to make the core docs vs collections docs. While the contributor sees something they want to change in the /latest/ version - Edit on GitHub goes to /devel/ and that will be under significant change for a few months. We may have to turn this feature off again for a time. Once the dust settles (aka Ansible 4.0.0 in late Spring), we can re-enable it. Alternately, we just live with contributor confusion for that timeperiod.

# Docsite states in time

**Jan/Feb - Ansible 3.0.0**, the docsite would have:
* Ansible Documentation for 3.0.0 published to existing docsite with /latest/ and 3.0.0 for version. This works best if the scenario etc guides are in the `ansible-collections` repo so we can tag/branch appropriately.
* Ansible 3.0.0 pulls from stable-2.10 where needed for user/developer guides etc
* Publish ansible-core/devel to a new url.
* NO changes to cannonical url.
* Update /latest/ to point to Ansible 3.0.0.

**Spring - ansible-core releases**
* Ansible Core Documentation published to new url- docs.ansible.com/ansible-core, as version 2.11 - collections details removed.
* NO /latest/ or cannonical url on this new docsite.

**Late Spring - Ansible 4.0.0 releases**
* Ansible Documentation 4.0.0 published and changed to /latest/ for its cannonical url.
* Ansible 4.0.0 pulls in stable-2.11 where needed.

**Future Releases**
Should be sustainable as the docs are now split, and latest / cannonical url only appears once, on the package docs.

# Publishing options

See https://hackmd.io/x0VwaKSYQCaHGJR4LelSEw for complete details.

**possible solution:** one publication pipeline takes appropriate docs content in each maintained stable branch of ansible/ansible and publishes it as docs.ansible.com/ansible-core; a separate publication pipeline takes docs content from a specific maintained stable branch of ansible/ansible and combines it with specific versions of collections and publishes it as docs.ansible.com/ansible.

This solution would let us maintain a single source for documentation of core/base features that appears in versioned HTML for both the ansible PyPI package and ansible-core.

We may need to pull the docs publishing files out of ansible/ansible - such as theme, scripts to build config.rst, etc etc.

# Related issues and other documents
https://github.com/ansible/ansible/issues/72032
https://github.com/ansible/ansible/issues/72717
https://github.com/ansible/ansible/pull/72287

## Older Draft Ideas
https://etherpad.opendev.org/p/ansible-documentation-split