Task #950

Updated by bmbouter over 8 years ago

We currently host our documentation at Read The Docs (RTD), Docs, which has a few problems. We have had issues with RTD Read The Docs being inflexible with our workflows. Also, RTD Read The Docs tracks our users with Google Analytics, and has also begun injecting advertisements into our project documentation. Read The RTD Docs's template also messes up the Pulp our 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. 

 OpenShift is a great tool that makes it very easy to host a website 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: Deliverables: 
 * Deploy Write one or more stories to accomplish a generic httpd instance t openshift owned by the user migration from RTD to OpenShift 
 * Make Develop a plan to use our Jenkins builder which publishes documentation nightly as a periodic job. This should use setup to build the Jenkins job builder template in pulp_packaging. 
 * The Jenkins job builder should clone, build, docs and push docs for platform and all plugins them to the openshift instance. OpenShift 
 * 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 workflow for comment 

 Additional Requirements: 
 * easy linking between X.Y versions of Pulp (like the documentation that aligns well with our existing docs do today workflow, 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 write a specific alpha/beta/RC 

 This is expected story to also resolve issues #831 and #840. document it