Project

Profile

Help

Task #950

Consolidate platform and plugin docs into a static site.

Added by rbarlow over 5 years ago. Updated over 1 year 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 - CURRENTRELEASE<a title="Actions" class="icon-only icon-actions js-contextmenu" href="#">Actions</a>
Related to Pulp - Task #831: Incorrect banners on RTD pagesCLOSED - CURRENTRELEASE

<a title="Actions" class="icon-only icon-actions js-contextmenu" href="#">Actions</a>
Blocks Pulp - Task #1888: Deploy the statically built docs to OpenShiftCLOSED - CURRENTRELEASE

<a title="Actions" class="icon-only icon-actions js-contextmenu" href="#">Actions</a>

Associated revisions

Revision 961e0b49 View on GitHub
Added by bmbouter over 4 years ago

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

Revision 2fa42342 View on GitHub
Added by bmbouter over 4 years ago

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.

Revision d33d5e59 View on GitHub
Added by bmbouter over 4 years ago

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

Revision 4ee47370 View on GitHub
Added by bmbouter over 4 years ago

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

Revision 14fb8928 View on GitHub
Added by bmbouter over 4 years ago

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

Revision cd640564 View on GitHub
Added by bmbouter over 4 years ago

Fixes pulp_rpm sphinx build errors and warnings.

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

Revision 595a6b0f View on GitHub
Added by bmbouter over 4 years ago

Fixes docs build errors and warnings

make html now builds cleanly without any errors or warnings.

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

Revision 7fa1527d View on GitHub
Added by bmbouter over 4 years ago

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

Revision 7fa1527d View on GitHub
Added by bmbouter over 4 years ago

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

Revision ac67da13 View on GitHub
Added by bmbouter over 4 years ago

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

Revision ac67da13 View on GitHub
Added by bmbouter over 4 years ago

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

Revision 61dd8f7e View on GitHub
Added by bmbouter over 4 years ago

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

Revision 61dd8f7e View on GitHub
Added by bmbouter over 4 years ago

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

Revision 59313dd4 View on GitHub
Added by bmbouter over 4 years ago

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

Revision 1192684c View on GitHub
Added by bmbouter over 4 years ago

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

Revision 1192684c View on GitHub
Added by bmbouter over 4 years ago

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

Revision 1192684c View on GitHub
Added by Brian Bouterse over 4 years ago

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

Revision 1192684c View on GitHub
Added by Brian Bouterse over 4 years ago

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

Revision 2f5ac2b3 View on GitHub
Added by bmbouter over 4 years ago

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

Revision c8ff0803 View on GitHub
Added by bmbouter over 4 years ago

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

Revision e57e6e60 View on GitHub
Added by bmbouter over 4 years ago

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

Revision 263183a8 View on GitHub
Added by bmbouter over 4 years ago

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

Revision 0e9aa58f View on GitHub
Added by bmbouter over 4 years ago

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

Revision 0e9aa58f View on GitHub
Added by bmbouter over 4 years ago

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

Revision 5f86bba4 View on GitHub
Added by bmbouter over 4 years ago

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

Revision 5f86bba4 View on GitHub
Added by bmbouter over 4 years ago

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

Revision 6ccd256a View on GitHub
Added by bmbouter over 4 years ago

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

Revision 6ccd256a View on GitHub
Added by bmbouter over 4 years ago

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

Revision 6ccd256a View on GitHub
Added by Brian Bouterse over 4 years ago

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

Revision 6ccd256a View on GitHub
Added by Brian Bouterse over 4 years ago

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

Revision a3c01c70 View on GitHub
Added by bmbouter over 4 years ago

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

Revision 50f14553 View on GitHub
Added by bmbouter over 4 years ago

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

Revision 11fa1ff4 View on GitHub
Added by bmbouter over 4 years ago

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

Revision 1eb3b376 View on GitHub
Added by bmbouter over 4 years ago

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

Revision 14a5c084 View on GitHub
Added by bmbouter over 4 years ago

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

Revision a33455da View on GitHub
Added by bmbouter over 4 years ago

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

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

Revision 82eea64a View on GitHub
Added by bmbouter over 4 years ago

Adds analytics tracking to docs.pulpproject.org

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

History

#1 Updated by bmbouter over 5 years ago

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

#2 Updated by bmbouter over 5 years ago

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

#3 Updated by bmbouter over 5 years ago

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

#4 Updated by mhrivnak about 5 years ago

  • Priority changed from High to Normal

#5 Updated by bmbouter over 4 years ago

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

#6 Updated by bmbouter over 4 years ago

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

#7 Updated by bmbouter over 4 years ago

  • Description updated (diff)

#8 Updated by bmbouter over 4 years ago

  • Tags Documentation added

#9 Updated by mhrivnak over 4 years ago

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

#10 Updated by bmbouter over 4 years ago

  • Status changed from NEW to ASSIGNED

#11 Updated by bmbouter over 4 years ago

  • Assignee set to bmbouter

#12 Updated by mhrivnak over 4 years ago

  • Sprint/Milestone changed from 20 to 21

#13 Updated by mhrivnak over 4 years ago

  • Sprint/Milestone changed from 21 to 22

#14 Updated by bmbouter over 4 years ago

  • Status changed from ASSIGNED to MODIFIED
  • % Done changed from 0 to 100

#15 Updated by bmbouter over 4 years ago

  • Platform Release set to 2.8.5

#16 Updated by bmbouter over 4 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.

#17 Updated by bmbouter over 2 years ago

  • Sprint set to Sprint 4

#18 Updated by bmbouter over 2 years ago

  • Sprint/Milestone deleted (22)

#19 Updated by bmbouter over 1 year ago

  • Tags Pulp 2 added

Please register to edit this issue

Also available in: Atom PDF