ansible-documentation
ansible-documentation copied to clipboard
ansible
Evaluate core docs on Read The Docs
To further align core with the rest of the projects in the Ansible ecosystem, we should host docs on Read The Docs (RTD) within the ansible namespace. This not only aligns core with the rest of the projects but brings increased visibility and access to the host infrastructure for the Ansible community.
Additionally the Ansible community team at Red Hat wants to keep working with (and supporting) the RTD community. They provide great tooling that really improves the documentation contributor experience and not just the ability to host generated HTML.
It is important to note that this proposal concerns the underlying host infrastructure for core docs only. There will be no replacement for the current web server until we can ensure no changes to https://docs.ansible.com/ansible-core/*/index.html will result from moving to RTD.
Here is a list of actions for this proposed evaluation:
### Tasks
- [x] Create a clearly marked stage project on RTD: https://readthedocs.org/projects/stage-ansible-core/
- [x] Add `.readthedocs.yaml` configuration to the "devel" branch.
- [x] Evaluate building PRs and other RTD features such as PDF builds for core docs for a limited test period.
- [x] Stand up versioned branches and translations on RTD.
- [ ] Modify the version switcher so that "2.16" points to the RTD branch of "stable-2.16"
- [ ] Determine what redirects need to be in place to avoid 404s or any SEO issues
@samccann Could you please remind what the status is with translations now? I seem to recall talking about that but we never set up the po files and translated content on readthedocs. Is that because the team that was providing translations, into Japanese only, is no longer doing that?
@oraNod - we don't have a translation for core-2.16. Take that as you will :-) I don't know if this means we'll never have one, or it's low on the priority.
Just popping back in here as a reminder we need to put up all active versions of core on RTD before we transition (2.16, 2.15, 2.14).
@samccann Yep. All active versions are there but the internal switcher needs work. On RTD the versioning is based on branch name so "stable-2.16" instead of "2.16".
https://ansible.readthedocs.io/projects/ansible-core/en/2.16/ vs https://ansible.readthedocs.io/projects/ansible-core/en/stable-2.16/
ah yeah. "Our" version switcher is a hack i snagged from someone's pr out in the ether 4+ years ago. Won't mind seeing the back of that one!
Note that PDF and EPUB builds on readthedocs are supported when using the default Sphinx configuration, https://docs.readthedocs.io/en/stable/config-file/v2.html#formats
If we want these formats we'll have to come up with something on our own, rather than using built-in RTD functionality.
I took a look at the builder docs in pdf form as an example and they seem to come out correctly. Not branded, but still usable for those who need offline docs. I'm not sure if your comment is referring to steps we'd need to take to brand the PDF or something else @oraNod ?
@samccann Builder docs use the RTD Sphinx configuration: https://github.com/ansible/ansible-builder/blob/633a85b9e0a84a83999fb4b07dc73a16832f6b5a/.readthedocs.yaml#L12
Core docs call the makefile with custom build commands: https://github.com/ansible/ansible-documentation/blob/5e170bf47319cce38e9eb8265d837cf83896331e/.readthedocs.yaml#L13
Ah gotcha. Thanks for the explanation (and so much for wishful thinking that this would create the pdfs folks have been asking for for years).
@oraNod FWIW you should be able to reproduce the same result by copying over those last commands it runs at the end of https://readthedocs.org/projects/ansible-builder/builds/23516789/:
$ python -m sphinx -T -b latex -d _build/doctrees -D language=en . $READTHEDOCS_OUTPUT/pdf
$ cat latexmkrc
$ latexmk -r latexmkrc -pdf -f -dvi- -ps- -jobname=ansible-builder -interaction=nonstopmode
$ python -m sphinx -T -W --keep-going -b epub -d _build/doctrees -D language=en . $READTHEDOCS_OUTPUT/epub
Sweet. Thanks @webknjaz I was actually of a mind to see if we could do something with latex to sort of hack PDF output. That looks like it could be an option.
Closing this issue as we've deleted the stage-ansible-core project in readthedocs and created ansible-core to take it's place. That project is now building at https://ansible.readthedocs.io/projects/ansible-core/devel/
WRT to the last two items in the task list, "version switcher" and "redirects", we should remove the built-in version switcher and use the RTD fly-out widget that lets you switch between versions instead. For the redirects, we'll need to handle them as part of the effort to migrate the docs.ansible.com subdomain to readthedocs. That is a larger effort and somewhat outside the scope of having an RTD project for core docs.