# Two Approaches to Split Docs

We've come up with two approaches that work to split up the core docs from Ansible docs. Both use different sphinx tricks to accomplish this, with pros and cons to each. This document summarizes these so we can decide the way forward.

**NOTE: We decided on the two index files approach below. The full details of both approaches are left here for reference.**

## Commonalities
Both approaches:
* Update the Makefiles to allow ``make coredocs``.
* Use the sphinx ``-c <path>`` option for a separate conf.py file to control the versions and some other parameters (see below for details).
* Update ``test/sanity/code-smell/docs-build.py`` to use ``core_htmldocs`` instead of ``base_htmldocs``.

## Two Index files
This approach uses a separate conf.py file for ansible package (in docs/docsite/ansible_pkg_rst directory).

* Uses exclude_pattern[] to exclude network, galaxy, and scenario guides and the individual porting guides and roadmap files from the appropriate sites.
* Uses symlinks in the Makefile to link index.rst from either ansible_index file for ansible or core_index.rst for core.

This approach creates two new files:
* A separate main index file (``ansible_index.rst``) to include all the guides, minus the base/core porting and roadmap guides. Anything not used is listed in the ``exclude_pattern[]`` in the matching conf.py.
* A new ``core_porting_guides.rst`` file to list only the ``ansible-core`` package guides. This approach ensures bookmarks to the porting guide index remains as the Ansible porting guide list.

WIP PR - https://github.com/ansible/ansible/pull/73421
### Pros and Cons
* Pro - fairly straight forward to list what goes in each docsite going forward.
* Con - requires a manual redirect for the Ansible docsite to redirect ``ansible_index.html`` to ``index.html`` or the webserver just lists the directories.

## Only:: directive approach
This approach:
* Uses the sphinx ``.. only::`` directive to include text conditionally within a build.
* This combines with the sphinx ``-t <tag>`` option to decide which rst content to include. Default tag is set in Makefile.sphinx as ``DOCSET= coredocs``. The Ansible build uses ``ansible_pkg``.
* Creates one new index file and reuses a previously orphaned index file for the scenario, network, and galaxy guides to get ``..only::`` directive working properly (see below Pros and Cons).

WIP PR - https://github.com/ansible/ansible/pull/73362

### Pros and Cons
* pro - doesn't require index redirect.
* Cons - the ``..only::`` directive is meant for text only. It has problems when used in or around the ``toctree`` directive. As such, the directive is sprinkled into more files than the alternate approach touches.
* Since this approach can't work in the ``toctree`` well in the main index.rst, I had to remove most of the captions. So the left-hand navigation is simplified (could be considered a pro or a con).
* 

## Future Releases
Going forward, either approach should be easy to maintain as the 'hard work' is done and what comes next would mostly work without changes.

## Backporting to 2.10
In order to create Ansible 3.x, these changes need to be backported to ``stable-2.10``. I don't see any difference in the approaches in terms of which is harder/easier to backport. The `base_htmldocs` to `core_htmldocs` change should be reverted so that 2.10 remains referencing ``base`` instead of ``core``.
It's also TBD how we would continue to make webdocs 'as is' for stable-2.10 (Ansible 2.10 docs) since ansible-base 2.10 at least will continue for some time, even if we can stop updating Ansible 2.10 once 3.0 releases. Perhaps we also publish ansible-base 2.10 as its own docsite?

# Use cases

Implementation will affect several elements of our docs ecosystem, including:
* the URLs on docs.ansible.com (our main goal)
* the Makefile on the devel branch
* the Makefile on the stable-2.10 branch
* the Makefile on future stable branches
* the main index file(s) on all branches
* the conf.py files on all branches
* the scripts in the Jenkins publication jobs

Here are some use cases to help us figure out where best to store and how best to manage the complexity we need:

## Release management with automated docs build
As a release manager, I want the documentation to be rebuilt with the latest information for each release I make, including z-stream releases for ansible-core. Looking ahead to a time when `latest` is Ansible 5.0 and ansible-core maintains 2.12, 2.11, 2.10, and LTS 2.9:

* what versions will we be ***changing/updating/releasing***?

As the release manager, I need to rebuild the current and near term future releases:
* 2.9, 2.10 (Ansible) to docs.ansible.com/ansible
* devel (core), 2.11 (core) to docs.ansible.com/ansible-core
* 3.x, 4.x (Ansible the package) to docs.ansible.com/ansible

**Note:** current build automation calls the docs jenkins job, which uses ``make webdocs``, but the current PR for the docsite uses ``make webdocs`` for Ansible docs, and ``make core-docs`` for core.

There are also two release processes:
* old Ansible (prior to collections), and ansible-base, ansible-core.
* Ansible the package (2.10, which will stop building once 3.x is released, 3.x, 4.x etc). Current plan is once a new major Ansible release happens, we stop building/supporting the prior release. It is TBD if that means we stop updating the docs for that EOL'd release.

### Solution
We can solve this as one of two options:

#### 3 Jenkins jobs
Create 3 jenkins builds - one for 2.10 and earlier, one for core, one for package. This requires the ansible release job to detect which scenario (2.9 or earlier, 2.10, or 2.11 and later) and pick the correct docs build to trigger (2.10 and earler, or core).

#### 2 Jenkins jobs
2 jenkins builds Ansible_docs and Ansible_pkg_docs. The Ansible_docs build has to detect if it is 2.10 or earlier (make webdocs) or 2.11/devel (make core-docs). We could use the $VERSION variable already in the jenkins builds to detect this and decide which url to use (/ansible/ or /ansible-core/ plus which make command to use (make webdocs or make coredocs). So Ansible_Build_Docs would be for 2.10 and earlier, and core docs, and be triggered by an ansible-base or ansible-core release. Ansible_pkg_Docs would be manual only, for Ansible 3.x and future releases.

##### Implementation
- Jenkins (if not mentioned, steps are similar to present jenkins job)
- BuildAnsibleDocs
- git checkout a specific branch
- call make coredocs
- BuildAnsiblePkgDocs
- Has a VERSION parameter
- git checkout a specific branch (?desirable?)
- call make webdocs VERSION=[2.10,3,4]
- Makefile (Largely finished here: https://github.com/ansible/ansible/pull/73421 )
- make coredocs
- Constructs a directory tree with only the files needed for ansible-core.
- Calls build-ansible.sh base
- make webdocs VERSION=[2.10,3,4]
- if $VERSION > 2.10:
- Constructs a directory tree with only the files needed for the ansible package
- Should there be a check that branch and VERSION match?
- Calls build-ansible.sh full --ansible-ver=$VERSION
- hacking/build-ansible.sh
- base: No change
- full:
- Add --ansible-ver flag
- Use ansible_version to determine which ansible-build-data file to get collection information from
- Maybe just this line: https://github.com/ansible/ansible/blob/devel/hacking/build_library/build_ansible/command_plugins/docs_build.py#L84
- antsibull-docs
- No change

#### One Jenkins job
A possible 3rd option - do it all with just one docs build:

* is it 2.10 and earlier - make webdocs to /ansible/ url
* is it 2.11 or later - make coredocs to /ansible-core/
* is it 2.11 or later AND a new package flag? make webdocs to /ansible/ url. Is it worth this extra complexity to keep us to one manual docs build?

## Local docs builds
As a technical writer or developer, I want to build the documentation locally to check for errors, review content in HTML format, and generally move my work forward. I would like three options:
* build a single rST page
* build only the rST pages in the ansible/ansible repo
* build the full ansible package documentation, including collections-based documentation and the rST pages in the ansible/ansible repo from the most recent stable release
* build all the versions listed under Release management above, from the various branches

## Automated build of devel docs (/ansible-core/ only)
As a contributor (staff or community), I want my changes to the documentation in the ansible/ansible `devel` branch to be published to docs.a.c/ansible-core/devel within a day.

## Manual build of latest docs (/ansible/ only)
As a team member, I want to rebuild docs.a.c/ansible/latest any time new contributions get backported.

## Manual build of older versioned docs on /ansible-core/
Same as Release management above?
As a team member, I want to rebuild older but still-maintained versions to docs.a.c/ansible-core/ any time new contributions get backported.

## Manual build of older versioned docs on /ansible/
As a technical writer, I need to be able to update even EOL'd releases with critical fixes to clarify information or points of confusion that readers are still finding in the EOL documentation. This means all versions that still exist in docs format - 2.3 - current.

Spelling this out further:
* 2.10 needs two builds - one for 2.10, and one that will produce Ansible 3.x. This means the PR that creates the docsite split will only be partially backported. Since stable-2.10 has no need for making core only docs, but does need the old ``make webdocs`` that makes all the docs, only backport portions of the PR that allow for creation of Ansible 3.x while keeping the ability to publish 2.10 for updates. Note both of these go to the same url.

## Findability of specific content
As a user of the community package, I need some documentation that currently lives mostly on the devel branch. However, the /ansible/ documentation is built from stable branches (currently from stable-2.10). How can I find this content?

* option - publish ansible/devel from the ansible/ansible devel branch, with either the existing (aka 3.x) list of collection versions, or pull the most recent collection version from Galaxy with a banner note to say these collection versions may not be included in the upcoming Ansible release (aka 4.x).
* option 2 - duplicate that information on both docsites. This would effectively just create two docsites with the same information, or we choose to only duplicate critical docs like the porting guides/roadmaps that are only maintained in devel.

### Porting Guides and Roadmaps

Porting guides and roadmaps are only published from /devel/ today. With the two-index docsite split, the /ansible-core/ docsite will NOT have the Ansible porting or roadmaps.

### What else?
Scenario and network guides are fixed at 2.10, which is even older than 3.x updates that exist in devel today. While many scenario guides are outdated/unmaintained, some are quite active (network, kubernetes, VMware).

###### tags: `archive`