owned this note
owned this note
Published
Linked with GitHub
# Docs for ansible-3.0.0
* ~~Need to build the docsite from multiple branches~~
* ~~Some will be from stable-2.10 and some from devel~~
Instead of building a pipeline to pull docs from multiple branches into docs.ansible.com, we will focus on hosting collection-related docs in collections, so the pipeline only has to deal with the relevant version of base/core for each Ansible package release.
## Criteria
Document what the user will be running in ansible-3.0.0. If the page is not related to what the user will run, ~~pull from devel~~ it should not be in ansible/ansible.
## Portions of docs that must come from stable-2.10
* user_guide/
* plugins (published under user guide today)
* installation_guide/intro_configuration - move this out of the installation_guide directory and into user_guide
* api
* one orphaned file, we could stop publishing it until more is added?
* inventory
* one orphaned file, we should integrate this into the user_guide. Maybe as part of a page that deals with specifying hosts on the command line? Or on a page that explains ansible inventory?
* galaxy
* user_guide reuses files from shared_snippets
* dev_guide - some repeated information from creating roles
* reference_appendices
* Except for release_and_maintenance.rst
## Portions of docs that must come from devel
### Documentation should come from elements of the package ONLY
* the Ansible package does not include any code from the devel branch
* for our sanity, and to drive the conversation about how to use the /docs/ folder within collections, let's hold the line here
* let's not build a temporary pipeline from devel that we do not want to maintain
* short-term this means the scenario guides will be out of date
* long-term this means we will have a workable, maintainable, visible system of managing documentation for code that lives in collections
~~### Ansible-3.0.0 is documented in ansible/ansible devel~~
* collections pages
* ~~collections/* (not index page). These are autogenerated from the collection versions in ansible-3.0.0~~
* scenario_guides/
* ~~These are maintained in devel but target the same collection versions that are in ansible-3.0.0, not necessarily the newest versions.~~
* network/
* ~~These are maintained in devel but target the same collection versions that are in ansible-3.0.0, not necessarily the newest versions.~~
### Unversioned
* ~~community/~~ aim for 4.0 or 5.0 release with community guide published from some other place if we want to make this unversioned
* roadmap/
* porting_guides (for Ansible 2.10, 3.x etc)
* reference_appendices/release_and_maintenance.rst
* This contains support timelines for all non-EOL ansible (and ansible-base) releases
* Move to roadmap/release_and_maintenance.rst ?
* dev_guide
* ~~We are going to convert this to single source across versions. As we make changes in newer versions of ansible, we need to document both the old and new behaviour here. That way, for instance, a collection developer can look here to see how to code their plugins for both older supported ansible releases and the next release.~~ Per discussion with core team and others on Jan 8 2021, keeping dev guide versioned.
* installation_guide/intro_installation.rst
* Convert this to single source across versions to cover Ansible>=2.10 and ansible-core >=2.11
* Move to installation_guide/index.rst ?
## Dealer's Choice
* release/maint/ pages ideally we create a new directory for this, porting guides, and roadmap and clearly separate core from Ansible. TBD
### Shared supporting files
* shared_snippets (must follow collection user_guide)
* We'll need to make sure to add to snippets but not remove from them (removal would break anything in the stable-2.10 docs that need them)
* images
* Same note as shared_snippets
Note: css and other theming may have similar requirements as shared_snippets?
**Can we make the themes on the two sites similar but not identical?**
## Implementation
### Discussion Jan 11
* minimal approach
* We need to get things into the collections ultimately
* If we document these things temporarily in the ansible/ansible devel docs, it would likely become permanent
* Right now we have leverage with the other teams because they want something:
* networking team, We're writing docs. We want them made public somewhere.
* Can we use that to get things the wway we want
Creating two identical docsites
So ansible-3 will be:
* stable-2.10 docs
* ansible-3 collection index
* Remove devel from the version dropdown? [no]
* Sometimes the next ansible will use the devel of ansible-core, other times it won't.
* We're going to keep publishing devel because this is all going to get redone for personas anyway. Removing the devel publication leads to issues like the roadmap being in devel-only right now.
* docs.ansible.com/ansible/3/
ansible-core will be:
* new jenkins job that will build devel
* docs.ansible.com/ansible-core/2.11
* add a way to publish to `/ansible-core` from the `devel` branch
* leave the current pipeline publishing from the devel branch to /ansible/devel
* possibly create a more logical /ansible/devel, maybe only updated when there's an ansible-core alpha/beta?
#### Mechanical to-do
To do:
* Test the pipeline
* jenkins jobs
* Currently two: nightly and manual, build to production
* Copy ansible build to ansible-core build
* Figure out why ansible build for "3" is broken. (Requires "3.x")
* Nightly core
* Manual core
* When we have this that makes sense, we still need old manual for 2.9
* Manual ansible
* Nightly ansible someday
* Needs two options for the version dropdown (if URL begins with /ansible/, use this list; if the URL begins with /ansible-core/, use that list)
* Can we make the two sites look different, so it's easy to tell which one you're looking at
* If we delete the /devel docs from /ansible/, we'll need to update the links that point to devel (for example the maintenance. page) so it points over to the core site.
* Figure out how to theme ansible-core differently from ansible
* Try to make everything doable in the Makefile. Jenkins is a light wrapper around that.
* divide the Release and Maintenance content between Core and Package
* try to reduce the number of redirects - reduce the cruft!
## Older Ideas
### Option A: "Easy"
* Docs build for 3.0 will know it is based on ansible-base 2.10.
* It will checkout stable-2.10.
* It will copy directories in the versioned list to a new temporary tree.
* It will checkout devel
* It will copy directories in the unversioned list to the existing temporary tree.
* It will then build the docs
#### Problems:
* Building docs from the tarball without internet access won't work with this procedure.
* Could fallback to building with what is in that particular version of ansible but it will be different than the docsite.
### Option B: "Variations on the theme"
* Option A but we construct the docs at tarball creation time.
#### Problems:
* Changes the release procedure for ansible-base/ansible-core
### Option C: "Two Docs"
* Separate the versioned and unversioned into two separate sphinx docs.
* Links will use intersphinx to link between the docs; ovver time, we should convert to use intersphinx explicitly so we don't get the wrong link by accident.
* Two make targets (possibly two directory structures too) to build the two docs
#### Problems:
* Less fleshed out than the alternative.
* Do we want to make this kind of change before the bigger personas revamp?