Project

Profile

Help

Task #950

closed

Consolidate platform and plugin docs into a static site.

Added by rbarlow almost 9 years ago. Updated almost 5 years ago.

Status:
CLOSED - CURRENTRELEASE
Priority:
Normal
Assignee:
Category:
-
Sprint/Milestone:
-
Start date:
Due date:
% Done:

100%

Estimated time:
Platform Release:
Groomed:
Yes
Sprint Candidate:
Yes
Tags:
Documentation, Pulp 2
Sprint:
Sprint 4
Quarter:

Description

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.

Make a prototype:

  • 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 and build docs for platform and all plugins nightly
  • 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.


Related issues

Related to Pulp - Issue #840: Beta and release candidate documentation is not availableCLOSED - CURRENTRELEASEActions
Related to Pulp - Task #831: Incorrect banners on RTD pagesCLOSED - CURRENTRELEASE

Actions
Blocks Pulp - Task #1888: Deploy the statically built docs to OpenShiftCLOSED - CURRENTRELEASEbmbouter

Actions

Also available in: Atom PDF