Task #950
Updated by bmbouter over 8 years ago
We currently host our documentation at Read The Docs (RTD), which has a few problems. We have had issues with RTD being inflexible with our workflows. Also, RTD tracks our users with Google Analytics, and has also begun injecting advertisements into our project documentation. The RTD template messes up the Pulp sidebar and makes it difficult for users to navigate our documentation. Also RTD places banners in strange places saying documentation is out of date when it isn't. Finally it prevents us from releasing docs with our beta and RC builds easily. It's just difficult for us to work with. Also all the docs are in their own "sites" which makes it very difficult to determine what Pulp does. These should be consolidated. OpenShift is a great tool that makes it very easy to host a static website and would still be free for us to use. Since we'd be in much greater control of the website, it wouldn't force any particular workflows upon us and wouldn't force our users to use trackware blocking tools if they are concerned about privacy. Make a prototype: * Deploy a generic httpd instance to openshift owned by the pulp-infra@redhat.com user * Make a Jenkins builder which publishes documentation nightly as a periodic job. This should use the Jenkins job builder template in pulp_packaging. * The Jenkins job builder should clone clone, build, and build push docs for platform and all plugins nightly to the openshift instance. * Develop a migration plan to make a smooth and great transition. This should come in the form of a new story. * Send the prototype and the rough migration plan to the community and the rest of the development team for comment * Consolidate all plugins and platform docs into one site. Additional Requirements: * easy linking between X.Y versions of Pulp (like the existing docs do today and the Django docs for example) * preserve the intersphinx structure we have today. This needs to continue to work * Fix any broken links that don't use intersphinx to resolve the link URL. This should be in its own PR that will be pushed as part of the migration plan. * The ability to publish docs for a specific alpha/beta/RC This is expected to also resolve issues #831 and #840.
.