Project

Profile

Help

Task #950

closed

Consolidate platform and plugin docs into a static site.

Added by rbarlow over 9 years ago. Updated over 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
Actions #1

Updated by bmbouter over 9 years ago

  • Related to Issue #840: Beta and release candidate documentation is not available added
Actions #2

Updated by bmbouter over 9 years ago

  • Related to Task #831: Incorrect banners on RTD pages added
Actions #3

Updated by bmbouter over 9 years ago

  • Subject changed from Develop a plan to host our docs in OpenShift to Prototype hosting our docs in OpenShift
  • Description updated (diff)
Actions #4

Updated by mhrivnak over 9 years ago

  • Priority changed from High to Normal
Actions #5

Updated by bmbouter over 8 years ago

  • Subject changed from Prototype hosting our docs in OpenShift to Consolidate platform and plugin docs into a static site.
  • Description updated (diff)
Actions #6

Updated by bmbouter over 8 years ago

  • Blocks Task #1888: Deploy the statically built docs to OpenShift added
Actions #7

Updated by bmbouter over 8 years ago

  • Description updated (diff)
Actions #8

Updated by bmbouter over 8 years ago

  • Tags Documentation added
Actions #9

Updated by mhrivnak over 8 years ago

  • Sprint/Milestone set to 20
  • Groomed changed from No to Yes
Actions #10

Updated by bmbouter over 8 years ago

  • Status changed from NEW to ASSIGNED
Actions #11

Updated by bmbouter over 8 years ago

  • Assignee set to bmbouter

Added by bmbouter over 8 years ago

Revision 961e0b49 | View on GitHub

Adds a skeleton sphinx docs project for crane.

This allows the docs builder jobs in Jenkins to build the docs for all projects in the same way (with Sphinx).

The fixedbugs has been tested by test building:

:fixedbugs:`2.0.0`

Also make html in the docs directory should not produce errors.

https://pulp.plan.io/issues/950 re #950

Added by bmbouter over 8 years ago

Revision 2fa42342 | View on GitHub

Revert "Adds a skeleton sphinx docs project for crane."

This reverts commit 961e0b49ebb6994774004dbb63509b5202c8e5bf.

This is being moved to 2.0-release and then merged forward to master.

Added by bmbouter over 8 years ago

Revision d33d5e59 | View on GitHub

Adds a skeleton sphinx docs project for crane.

This allows the docs builder jobs in Jenkins to build the docs for all projects in the same way (with Sphinx).

The fixedbugs has been tested by test building:

:fixedbugs:`2.0.0`

Also make html in the docs directory should not produce errors.

https://pulp.plan.io/issues/950 re #950

Added by bmbouter over 8 years ago

Revision 4ee47370 | View on GitHub

Migrates README.rst content into the sphinx built project

  • Maintains a basic description in the README which links to the rest content in it's new location.

  • Also fixes several formatting errors which Sphinx identified This causes make html to produce html output that looks good without any warnings or errors.

  • Adds a flake8 ignore statement to ignore the docs/conf.py file

Prior to this the build process would fail with:

Sphinx error:
master file /home/bmbouter/devel/working/crane/docs/index.rst not found

This commit is designed to restructure the current docs so it is being merged to 2.0-release and merged forward from there.

https://pulp.plan.io/issues/950 re #950

Added by bmbouter over 8 years ago

Revision 14fb8928 | View on GitHub

Configures Sphinx docs config to not look for static media

Prior to this fix when building the docs you would see a warning like:

html_static_path entry u'/path/to/pulp_ostree/docs/_static' does not exist

https://pulp.plan.io/issues/950 re #950

Added by bmbouter over 8 years ago

Revision cd640564 | View on GitHub

Fixes pulp_rpm sphinx build errors and warnings.

https://pulp.plan.io/issues/950 re #950

Added by bmbouter over 8 years ago

Revision 595a6b0f | View on GitHub

Fixes docs build errors and warnings

make html now builds cleanly without any errors or warnings.

https://pulp.plan.io/issues/950 re #950

Added by bmbouter over 8 years ago

Revision 7fa1527d | View on GitHub

Fixes platform docs build warnings/errors and compilation of images

  • Docs build without any warnings or errors
  • Enables strict building in python-sphinx project
  • Digram sources moved to a sphinx project level directory
  • Pre-made images moved to a sphinx project level directory
  • Diagrams compile and cannot be saved back to the repo

re #950 https://pulp.plan.io/issues/950

Added by bmbouter over 8 years ago

Revision 7fa1527d | View on GitHub

Fixes platform docs build warnings/errors and compilation of images

  • Docs build without any warnings or errors
  • Enables strict building in python-sphinx project
  • Digram sources moved to a sphinx project level directory
  • Pre-made images moved to a sphinx project level directory
  • Diagrams compile and cannot be saved back to the repo

re #950 https://pulp.plan.io/issues/950

Added by bmbouter over 8 years ago

Revision ac67da13 | View on GitHub

Fixes formatting error in 2.3 release notes

This was recently intorduced when the 2.3 release notes were adjusted during the 2.8.3 release.

re #950 https://pulp.plan.io/issues/950

Added by bmbouter over 8 years ago

Revision ac67da13 | View on GitHub

Fixes formatting error in 2.3 release notes

This was recently intorduced when the 2.3 release notes were adjusted during the 2.8.3 release.

re #950 https://pulp.plan.io/issues/950

Added by bmbouter over 8 years ago

Revision 61dd8f7e | View on GitHub

Fixes RTD pages which don't build plantuml images at build time.

These images were commited before in the repo with commit ab1e5c833d3e928252eef0b4b6ff05d06b1a504c. They are being brought back so that read the docs can have static images to use.

git already knows about these images so there is no additional storage space used by this commit.

This will be merged to 2.8-release -> 2.8-dev -> master

The future build machinery is introduced with 7fa1527d419a2c8f20979c145a8e0559c7587218 and will build all .dot diagrams freshly with each docs build. Once we no longer use Read the Docs we will remove these two images from _static and revert the .. image:: to use the images available at build time in the _diagrams directory.

re #950 https://pulp.plan.io/issues/950

Added by bmbouter over 8 years ago

Revision 61dd8f7e | View on GitHub

Fixes RTD pages which don't build plantuml images at build time.

These images were commited before in the repo with commit ab1e5c833d3e928252eef0b4b6ff05d06b1a504c. They are being brought back so that read the docs can have static images to use.

git already knows about these images so there is no additional storage space used by this commit.

This will be merged to 2.8-release -> 2.8-dev -> master

The future build machinery is introduced with 7fa1527d419a2c8f20979c145a8e0559c7587218 and will build all .dot diagrams freshly with each docs build. Once we no longer use Read the Docs we will remove these two images from _static and revert the .. image:: to use the images available at build time in the _diagrams directory.

re #950 https://pulp.plan.io/issues/950

Added by bmbouter over 8 years ago

Revision 59313dd4 | View on GitHub

Enables strict mode for sphinx docs builds

This causes errors to be noticed by the Jenkins job which is the motivation for this change.

re #950 https://pulp.plan.io/issues/950

Added by bmbouter over 8 years ago

Revision 1192684c | View on GitHub

Enables strict mode for sphinx docs builds

This causes errors to be noticed by the Jenkins job which is the motivation for this change.

re #950 https://pulp.plan.io/issues/950

Added by bmbouter over 8 years ago

Revision 1192684c | View on GitHub

Enables strict mode for sphinx docs builds

This causes errors to be noticed by the Jenkins job which is the motivation for this change.

re #950 https://pulp.plan.io/issues/950

Added by Brian Bouterse over 8 years ago

Revision 1192684c | View on GitHub

Enables strict mode for sphinx docs builds

This causes errors to be noticed by the Jenkins job which is the motivation for this change.

re #950 https://pulp.plan.io/issues/950

Added by Brian Bouterse over 8 years ago

Revision 1192684c | View on GitHub

Enables strict mode for sphinx docs builds

This causes errors to be noticed by the Jenkins job which is the motivation for this change.

re #950 https://pulp.plan.io/issues/950

Added by bmbouter over 8 years ago

Revision 2f5ac2b3 | View on GitHub

Enables strict mode for sphinx docs builds

This causes errors to be noticed by the Jenkins job which is the motivation for this change.

re #950 https://pulp.plan.io/issues/950

Added by bmbouter over 8 years ago

Revision c8ff0803 | View on GitHub

Enables strict mode for sphinx docs builds

This causes errors to be noticed by the Jenkins job which is the motivation for this change.

re #950 https://pulp.plan.io/issues/950

Added by bmbouter over 8 years ago

Revision e57e6e60 | View on GitHub

Enables strict mode for sphinx docs builds

This causes errors to be noticed by the Jenkins job which is the motivation for this change.

re #950 https://pulp.plan.io/issues/950

Added by bmbouter over 8 years ago

Revision 263183a8 | View on GitHub

Enables strict mode for sphinx docs builds

This causes errors to be noticed by the Jenkins job which is the motivation for this change.

re #950 https://pulp.plan.io/issues/950

Added by bmbouter over 8 years ago

Revision 0e9aa58f | View on GitHub

Adds intersphinx name for 'platform' to sphinx config

The plugins refer to platform using the intersphinx keyword 'platform'. As the plugin content will start being built as one sphinx project, the platform sphinx must also support the 'platform' keyword.

re #950 https://pulp.plan.io/issues/950

Added by bmbouter over 8 years ago

Revision 0e9aa58f | View on GitHub

Adds intersphinx name for 'platform' to sphinx config

The plugins refer to platform using the intersphinx keyword 'platform'. As the plugin content will start being built as one sphinx project, the platform sphinx must also support the 'platform' keyword.

re #950 https://pulp.plan.io/issues/950

Actions #12

Updated by mhrivnak over 8 years ago

  • Sprint/Milestone changed from 20 to 21

Added by bmbouter over 8 years ago

Revision 5f86bba4 | View on GitHub

Reverting strict mode so that Koji can build RPMs again

Koji does not allow for the loading of intersphinx inv files due to Mock's restriction of internet access during build time.

This will get reintroduced later after we have a better plan for how to handle intersphinx in our Koji environment.

re #950 https://pulp.plan.io/issues/950

Added by bmbouter over 8 years ago

Revision 5f86bba4 | View on GitHub

Reverting strict mode so that Koji can build RPMs again

Koji does not allow for the loading of intersphinx inv files due to Mock's restriction of internet access during build time.

This will get reintroduced later after we have a better plan for how to handle intersphinx in our Koji environment.

re #950 https://pulp.plan.io/issues/950

Added by bmbouter over 8 years ago

Revision 6ccd256a | View on GitHub

Reverting strict mode so that Koji can build RPMs again

Koji does not allow for the loading of intersphinx inv files due to Mock's restriction of internet access during build time.

This will get reintroduced later after we have a better plan for how to handle intersphinx in our Koji environment.

re #950 https://pulp.plan.io/issues/950

Added by bmbouter over 8 years ago

Revision 6ccd256a | View on GitHub

Reverting strict mode so that Koji can build RPMs again

Koji does not allow for the loading of intersphinx inv files due to Mock's restriction of internet access during build time.

This will get reintroduced later after we have a better plan for how to handle intersphinx in our Koji environment.

re #950 https://pulp.plan.io/issues/950

Added by Brian Bouterse over 8 years ago

Revision 6ccd256a | View on GitHub

Reverting strict mode so that Koji can build RPMs again

Koji does not allow for the loading of intersphinx inv files due to Mock's restriction of internet access during build time.

This will get reintroduced later after we have a better plan for how to handle intersphinx in our Koji environment.

re #950 https://pulp.plan.io/issues/950

Added by Brian Bouterse over 8 years ago

Revision 6ccd256a | View on GitHub

Reverting strict mode so that Koji can build RPMs again

Koji does not allow for the loading of intersphinx inv files due to Mock's restriction of internet access during build time.

This will get reintroduced later after we have a better plan for how to handle intersphinx in our Koji environment.

re #950 https://pulp.plan.io/issues/950

Added by bmbouter over 8 years ago

Revision a3c01c70 | View on GitHub

Reverting strict mode so that Koji can build RPMs again

Koji does not allow for the loading of intersphinx inv files due to Mock's restriction of internet access during build time.

This will get reintroduced later after we have a better plan for how to handle intersphinx in our Koji environment.

re #950 https://pulp.plan.io/issues/950

Added by bmbouter over 8 years ago

Revision 50f14553 | View on GitHub

Reverting strict mode so that Koji can build RPMs again

Koji does not allow for the loading of intersphinx inv files due to Mock's restriction of internet access during build time.

This will get reintroduced later after we have a better plan for how to handle intersphinx in our Koji environment.

re #950 https://pulp.plan.io/issues/950

Added by bmbouter over 8 years ago

Revision 11fa1ff4 | View on GitHub

Reverting strict mode so that Koji can build RPMs again

Koji does not allow for the loading of intersphinx inv files due to Mock's restriction of internet access during build time.

This will get reintroduced later after we have a better plan for how to handle intersphinx in our Koji environment.

re #950 https://pulp.plan.io/issues/950

Added by bmbouter over 8 years ago

Revision 1eb3b376 | View on GitHub

Reverting strict mode so that Koji can build RPMs again

Koji does not allow for the loading of intersphinx inv files due to Mock's restriction of internet access during build time.

This will get reintroduced later after we have a better plan for how to handle intersphinx in our Koji environment.

re #950 https://pulp.plan.io/issues/950

Actions #13

Updated by mhrivnak over 8 years ago

  • Sprint/Milestone changed from 21 to 22

Added by bmbouter over 8 years ago

Revision 14a5c084 | View on GitHub

Adds a docs builder Jenkins job

This job nightly build one sphinx project which includes platform and all plugins develped by the core dev team.

This job uses the docs-ownership so it has owners. It also uses the e-mail notify macro for owner notification on failure.

The version of each plugin is specified in the releases yaml files used by the build infrastructure. Each repo is cloned freshly with each build.

This job comes with additional rst files which are merged in prior to the build. This additional content organizes all of the other content which was not designed to be shown as one site.

It also deploys a robots.txt for the root of the docs site.

https://pulp.plan.io/issues/950 re #950

Added by bmbouter over 8 years ago

Revision a33455da | View on GitHub

Beta and RC docs should live at /en/x.y/testing/

https://pulp.plan.io/issues/950 fixes #950

Actions #14

Updated by bmbouter over 8 years ago

  • Status changed from ASSIGNED to MODIFIED
  • % Done changed from 0 to 100
Actions #15

Updated by bmbouter over 8 years ago

  • Platform Release set to 2.8.5
Actions #16

Updated by bmbouter over 8 years ago

  • Status changed from MODIFIED to CLOSED - CURRENTRELEASE
  • Platform Release deleted (2.8.5)

This is already in production so I'm marking as closed.

Added by bmbouter over 8 years ago

Revision 82eea64a | View on GitHub

Adds analytics tracking to docs.pulpproject.org

https://pulp.plan.io/issues/950 re #950

Actions #17

Updated by bmbouter almost 7 years ago

  • Sprint set to Sprint 4
Actions #18

Updated by bmbouter almost 7 years ago

  • Sprint/Milestone deleted (22)
Actions #19

Updated by bmbouter over 5 years ago

  • Tags Pulp 2 added

Also available in: Atom PDF