Previous Releases link broken for ecosystem projects

[coruscating]

The Qiskit Experiments 0.5 docs have just been published, and the Previous Releases links on the sidebar are broken because they're hard coded to /documentation/stable/{{ version }}/index.html:

qiskit_sphinx_theme/qiskit_sphinx_theme/pytorch_base/sidebar.html

Line 21 in 29277ce

<div class="sidebar-l2"><a href="/documentation/stable/{{ version }}/index.html">{{ version }}</a></div>

The Qiskit Experiment stable link is at /documentation/experiments/stable/{{ version }}/index.html, so this doesn't work. I would think the easiest solution is adding another html_context variable for the path and letting users customize that in conf.py.

[coruscating]

Also, since ecosystem documentation is deploying to both /documentation and /ecosystem after Qiskit/qiskit.org#3038, the link has to be correct for each site, so maybe the solution mentioned above isn't going to work.

[Eric-Arellano]

@1ucian0 suggestions for how we should approach this?

[coruscating]

For the docs at the root path, whether it's /documentation or /ecosystem, changing the link to the relative path ./stable/{{ version }}/index.html should work. However, that breaks for the links in the docs for previous versions since it will try to go to /stable/{{ version }}/stable/{{ version }}/index.html. Maybe the links in previous versions can be built differently?

[1ucian0]

Hmm... my idea of deploy in /documentation and in /providers seems that is not working. I'll take a look.

[1ucian0]

I think the solution is to avoid hardcoding the root directory in the template. Probably using something like pathto or root_doc.

[coruscating]

This is not an /ecosystem specific problem so maybe the issue title should be updated. I tested with pathto and root_doc but they only generate relative paths, and I don't see how they solve our problem after #259, which is:

On https://qiskit.org/documentation/experiments, the link is ./stable/0.5, which goes to https://qiskit.org/documentation/experiments/stable/0.5. This works.

On https://qiskit.org/documentation/experiments/stable/0.5, the link is still ./stable/0.5, which goes to https://qiskit.org/documentation/experiments/stable/0.5/stable/0.5. This doesn't work. The sphinx build itself has no idea that we're at a different root URL. If anything, we need a way to get the actual URL in jinja and change the link based on it. Or we have to build previous release sites differently.

[Eric-Arellano]

To summarize the above discussion:

Below are the places where the previous version URL can be clicked from. We need to make sure the URL works from each of these locations.

Terra:

• documentation/
• documentation/stable/0.5/index.html

Ecosystem, old scheme:

• documentation/experiments/
• documentation/experiments/stable/0.5/index.html

Ecosystem, new scheme:

• ecosystem/nature/
• ecosystem/nature/stable/0.5/index.html

Right now, we hardcode to /documentation/stable/<version>/index.html. That correctly handles both URL schemes for Terra. But not the ecosystem.

#259 will fix for all 3 scenarios the link from home, e.g. documentation/. But it will break the link if you are already on /stable/, e.g. /documentation/stable/0.41/index.html would now become /documentation/stable/0.41/index.html/documentation/stable/0.39/index.html.

If anything, we need a way to get the actual URL in jinja and change the link based on it. Or we have to build previous release sites differently.

I agree. We can do this via JavaScript looking at window.location.href. I'll work on this today.

[Eric-Arellano]

@1ucian0 now that we have redirects of documentation/<proj> to ecosystem/<proj>, I'm not sure how this updates what I say right above?

Are you publishing old builds of the docs under ecosystem/, or only the most recent builds? Although, I think maybe no ecosystem projects have been using the previous versions feature so this is irrelevant?

Are we ever publishing anymore to documentation/?

[1ucian0]

I think what you have above still applies. Currently, old versions of qiskit-experiments are deployed in https://qiskit.org/ecosystem/experiments/stable/<version>/:

https://github.com/Qiskit/qiskit-experiments/blob/5d840c89e7b008644a0b46c86db5afbc05cab4e8/tools/deploy_documentation.sh#L39

Because the CDN redirect, /documentation/experiments/ and /ecosystem/experiments/ should behave similarly:

[/^qiskit\.org\/documentation\/experiments\/(.*)/, 'qiskit.org/ecosystem/experiments/$1'],

Are you publishing old builds of the docs under ecosystem/, or only the most recent builds?

Depends a lot on the project. Not every project keeps old build. The documentation-ecosysytem change should not change what projects are doing.

Right now, we hardcode to /documentation/stable//index.html. That correctly handles both URL schemes for Terra. But not the ecosystem.

That's right.