Pulp

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.

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.

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.

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.

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

Thanks for the direction!

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

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.

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.

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!

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

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?

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

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.

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.

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/

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