Users should set docs_url_prefix for Translations and Previous Releases
#321
Conversation
tests/py/previous_releases_test.py
Outdated
| from qiskit_sphinx_theme.previous_releases import get_previous_versions_url | ||
|
|
||
|
|
||
| def test_get_previous_versions_url() -> None: |
There was a problem hiding this comment.
could you add a docstring please :)
Also might be nice to parameterise this test? Its a small test so not a big deal if not, just a nice to have
There was a problem hiding this comment.
Also also, there seem to be much fewer test cases covered here compared to the whole test file above that got deleted. Is there a reason why?
There was a problem hiding this comment.
Also might be nice to parameterise this test? Its a small test so not a big deal if not, just a nice to have
Sure, done.
there seem to be much fewer test cases covered here compared to the whole test file above that got deleted. Is there a reason why?
Yeah, it's because this implementation is substantially simpler. We don't need to extract out what the docs_url_prefix is anymore using fancy regex on the current URL. The user already tells us now via conf.py. And we know the version from the Jinja template. So, all we're doing is combining those two values with an f-string.
| docs_url_prefix = "ecosystem/finance" | ||
| ``` | ||
|
|
||
| ## Enable Previous Releases |
There was a problem hiding this comment.
cc @coruscating - could you please read through these instructions?
| ("", "index", "/index.html"), | ||
| ("", "subdir/my_page", "/subdir/my_page.html"), |
There was a problem hiding this comment.
We now error if you set "" because it won't work for any project we have in the wild: they all have a prefix.
The only one I was confused by is Terra. They set this value to documentation, but in a weird way in some scripts that took me a while to find. So, at first, I incorrectly thought Terra was setting the value to "".
README.md
Outdated
| Then, update your `conf.py`: | ||
|
|
||
| * Ensure that `qiskit_sphinx_theme` is in the `extensions` setting. | ||
| * Add to the option `html_context` an entry for `version_list` with a list of the prior versions, e.g. `["0.4", "0.5"]`. Each of these versions must be deployed with the above `stable/<version>` URL scheme. |
There was a problem hiding this comment.
Some projects use an auto-generated list: https://github.com/Qiskit/qiskit-experiments/blob/a8f9de8b39774ce2c22c0ec5ae19bd7f023bfeca/docs/conf.py#L185
Which method should be listed here as the standard?
There was a problem hiding this comment.
I want to investigate in #307 if we can get more standardization for Previous Releases. In the meantime, it's up to each project to do this how they want.
I rewrote this section to give more context. Thanks for the feedback!
|
|
||
| This feature allows you to link to previous versions of the docs in the left sidebar. | ||
|
|
||
| First, start additionally deploying your docs to `<project-prefix>/stable/<version>/`, e.g. `/ecosystem/finance/stable/0.5/index.html`. See https://github.com/Qiskit/qiskit-experiments/blob/227867937a08075092cd11756214bee3fb1d4d3d/tools/deploy_documentation.sh#L38-L39 for an example. |
There was a problem hiding this comment.
I think I'd prefer an inline rclone example here that works with your ecosystem/finance example rather than a link to a different repo's code.
There was a problem hiding this comment.
I was thinking it's better to link to a repo because it's a more complete example, such as showing how to determine what the version is. It seems like every project is using the same script to deploy docs, so I think this should be fine?
…into docs-url-prefix
Closes #303.
Everyone's local copy of
versionutils.pyalready had the optioncontent_prefix, which had to be set to e.g.ecosystem/financeordocumentation. That was already being used by the Translations feature. (But it was only for their local projects; qiskit_sphinx_theme never had this option.)This PR makes some improvements to
content_prefix:docs_url_prefix<a href>an actual link, which better complies with the Semantic Web.