Project

Profile

Help

Story #2673

As a user browsing on docs.pulpproject.org, I can see a banner displaying when I am browsing docs of an unsupported release

Added by bmbouter almost 5 years ago. Updated almost 3 years ago.

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

0%

Estimated time:
Platform Release:
2.14.0
Groomed:
Yes
Sprint Candidate:
Yes
Tags:
Pulp 2
Sprint:
Quarter:

Description

A banner should be put on the top of every page docs page saying "This documentation is for an unsupported version of Pulp. Consider upgrading to a supported version."

For example something like what the Celery docs have: http://docs.celeryproject.org/en/3.1/userguide/workers.html

After discussion below a dynamic approach should be used. This involves creating a new 'supported_releases.json' file hosted at https://github.com/pulp/pulp_packaging/tree/master/ci/config/releases/ with all x.y strings in it as a list. Here is an example with 2.12 and 3.0 showing as supported:

["2.12", "3.0"]

Then some javascript should check the docs version of the current page and if it is not in the x.y stream that is supported, show the banner.

History

#1 Updated by bmbouter almost 5 years ago

  • Description updated (diff)

In terms of displaying the banner, I think we want to do something with Sphinx. Maybe like this: http://stackoverflow.com/a/28811505

To configure the banner configured for some jobs and not others I can think of two approaches.

1. A static approach. This approach would include a build option in JJB that would cause the banner settings to be enabled. Deprecating the old docs would become a step in the release engineering pipeline to update JJB and trigger a final docs build of a deprecated version when a new GA release is made.

2. A dynamic approach. This would be an AJAX style call which checks a structured field probably hosted via raw github at a place like this. This would allow us to change the data being checked and all doc behaviors update without a page reload. Keeping that field up to date would also like

#2 Updated by semyers almost 5 years ago

bmbouter wrote:

1. A static approach. This approach would include a build option in JJB that would cause the banner settings to be enabled. Deprecating the old docs would become a step in the release engineering pipeline to update JJB and trigger a final docs build of a deprecated version when a new GA release is made.

2. A dynamic approach. This would be an AJAX style call which checks a structured field probably hosted via raw github at a place like this. This would allow us to change the data being checked and all doc behaviors update without a page reload. Keeping that field up to date would also like

I don't have alternative approaches to suggest. Among these, I prefer the dynamic approach to the manual approach. At the moment, Pulp 3 continues to use the release config approach, so we should be able to continue using it with minor modifications in Pulp 3 processes as well.

#3 Updated by bmbouter almost 5 years ago

  • Description updated (diff)

#4 Updated by amacdona@redhat.com almost 5 years ago

I would like to see the option of having more than one supported x.y release. For example, we will probably still consider the latest 2.Y release to be supported even after we release 3.0.

#5 Updated by bmbouter almost 5 years ago

  • Description updated (diff)

I've revised it to allow the data structure to be a list instead of a a single string. This allows for multiple supported versions in the future.

#6 Updated by semyers almost 5 years ago

  • Groomed changed from No to Yes
  • Sprint Candidate changed from No to Yes

I recently found this nifty project:
https://github.com/Robpol86/sphinxcontrib-versioning

It sorta does what we want here, but is terribly confused by our tremendous number of tags, and while it does have whitelisting features, I suspect it would be more work to get this script to deal with our current plugin-merging behavior, branch layout, etc, then it would be to modify our existing docs builder to add the banner as described in this story. sphinxcontrib-versioning might be useful as a reference, and potentially as a project that we could contribute some of our work to in order to make it a better fit for our needs.

For now, I think this story is good-to-go as written, should be considered for an upcoming sprint.

#7 Updated by semyers almost 5 years ago

semyers wrote:

I recently found this nifty project:
https://github.com/Robpol86/sphinxcontrib-versioning

It sorta does what we want here, but is terribly confused by our tremendous number of tags...

bmbouter thought it might be good to make sure this doesn't go by quite so understated, so I'll clarify: It's not so much that the versioning plugin is terribly confused, so much as it doesn't work at all, and nearly melts my laptop in the process of not working. I do think that it might have a shot at succeeding if we cleaned up all the extra tags that we have, but the whitelisting features it offers aren't enough to cope.

#8 Updated by jwelborn over 4 years ago

asmacdo showed me this issue.

I'd be interested in adding a short jquery script to check the contents of the ".version" element and add a warning at the top of the page for all non-supported versions. If the script can be included in the header of the template sphinx uses to generate docs it would just needed to be updated when the "supported versions" change.

I'm very new to sphinx and autodoc generation, so if someone could point me towards the parent template sphinx uses when it generates html I'll take a stab at it and send a pull request if I get something working.

#9 Updated by bizhang over 4 years ago

jwelborn Thank you for taking a look at this!

Currently pulp is using the sphinx_rtd_theme [0].

Pulp has a templates_path configuration option in pulp/docs/conf.py [1] pointing to a _templates directory. You should create this in under pulp/docs since it currently does not exist.

It look like you can extend the default layout like this: https://stackoverflow.com/a/5585354/953251

New JS files should be added to pulp/docs/_static and can be included in your layout like this: https://github.com/rtfd/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/layout.html#L199

[0] https://github.com/rtfd/sphinx_rtd_theme
[1] https://github.com/pulp/pulp/blob/master/docs/conf.py#L39

#10 Updated by jwelborn over 4 years ago

Thanks for the direction!

I'll get on this and see what I can come up with.

#11 Updated by amacdona@redhat.com over 4 years ago

  • Status changed from NEW to ASSIGNED
  • Assignee set to amacdona@redhat.com

#12 Updated by jwelborn over 4 years ago

  • Assignee changed from amacdona@redhat.com to jwelborn

#13 Updated by jwelborn over 4 years ago

I have a script that can check the version number against a set of values passed via the docs conf.py file and generate a warning message as needed.

If I'm correct, the docs are generated based on the git branch for each version.

Is there a base branch where I can add a "supported version" list to that the conf.py from every branch can access it? Same question for the script.

#14 Updated by bmbouter over 4 years ago

jwelborn wrote:

I have a script that can check the version number against a set of values passed via the docs conf.py file and generate a warning message as needed.

Is it a javascript script? I think the script that needs to check should be some jQuery checker or similar. The script would be run on every page loaded and would asynchronously fetch the supported_releases.json and check if the "not supported" banner should be displayed.

If I'm correct, the docs are generated based on the git branch for each version.

The docs are really built by branch name. Those branch names are all captured here but note that all of those files are actually on "master". So you can always read the github.com/pulp/pulp_packaging/ repo's master branch. That is also where I think the supported_releases.json file needs to be introduced.

Is there a base branch where I can add a "supported version" list to that the conf.py from every branch can access it? Same question for the script.

Yes it would be a new file called supported_releases.json here

Keep the questions coming! We want to help support your contribution. You're also welcome to ask in #pulp-dev on freenode as well.

#15 Updated by jwelborn over 4 years ago

2 more questions:

Which versions of pulp are supported?

For the AJAX call, should I use the github contents API to get the URL of supported_releases.json, or is there a URL that will get me straight to the file on the server?

Thanks again for letting me hack on pulp!

#16 Updated by bmbouter over 4 years ago

Right now it's 2.13.z so that would be '2.13' since the docs are built for any given x.y and just updated with every z release. The 2.14 GA announcement will also happen on 2.14, but can also be followed here: https://pulp.plan.io/projects/pulp/wiki/2140_Release_Status

We want to have the ability to have multiple supported versions, even though there is only one currently. For a demo the file could temporarily also have say '2.11' too.

I like to fetch from github using the 'raw' url from gihutb like: https://raw.githubusercontent.com/pulp/pulp_packaging/master/ci/config/releases/2.12-release.yaml

#17 Updated by jwelborn over 4 years ago

Final(?) questions.

Right now, I have the javascript in a script tag here

Here it will be added to each versions' docs the next time they are built/rebuilt. Does this take care of the doc builder portion?

For the "Update the build docs" step, am I correct to think I should be adding a step to the building instructions?

#18 Updated by bizhang over 4 years ago

jwelborn I think that's all you need to do in the doc builder.
For the docs, updating Building Instructions sounds right. I think it should be done here as a bullet point: https://docs.pulpproject.org/dev-guide/contributing/building.html#updating-docs

#19 Updated by jwelborn over 4 years ago

Since this will only really apply from the present forward, is it OK for me to just change the docs on the master pulp branch, or should i go back and change all the branches from 2.4 on?

If the master is all I need to update, I can send the pull request now.

#20 Updated by bmbouter over 4 years ago

I'm thinking that if you can submit your PR against 2.13-dev that would be the best place to start. Ultimately, I think we want it on all the following branches

2.8-release
2.9-release
2.10-release
2.11-release
2.12-release
2.13-dev
master

You PR against 2.13-dev would get into into 2.13 eventually and we would merge it to master (2.14). Then we can take care of cherry picking it back to the 2.*-release branches and then have Jenkins rebuild each of those docs branches.

I'd be interested to hear if others also think this is the right approach.

#21 Updated by bizhang over 4 years ago

  • Status changed from ASSIGNED to MODIFIED

#22 Updated by pcreech over 4 years ago

  • Platform Release set to 2.14.0

#23 Updated by bmbouter over 4 years ago

Would it be possible for us to have the banner applied to all 2.8+ docs? I think those older releases are the main place I think about having that banner. For instance these docs would show the banner: http://docs.pulpproject.org/en/2.8/

#24 Updated by bmbouter over 4 years ago

I applied a script that bizhang wrote which added the necessary html to all pages. This allows us to update all of the old docs without rebuilding them in Jenkins. If they ever were rebuilt with Jenkins the correct html would also be produced, this was just an easier way.

For posterity the script used I saved as a gist here: https://gist.github.com/bmbouter/dc4871b87456e427dbb697c4bb82102e

I also added a landing page for the 2.6 and 2.7 docs which contains a similar warning. Previously those only were directory listings so we needed a new index.html page for each to allow us to have the warnings. Those pages are here and here

#25 Updated by pcreech over 4 years ago

  • Status changed from MODIFIED to 5

#26 Updated by pcreech over 4 years ago

  • Status changed from 5 to CLOSED - CURRENTRELEASE

#27 Updated by bmbouter almost 3 years ago

  • Tags Pulp 2 added

Also available in: Atom PDF