-
Notifications
You must be signed in to change notification settings - Fork 29
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Users should set docs_url_prefix
for Translations and Previous Releases
#321
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice work so far!
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM, new tests look great! 🚀
just left one tiny optional suggestion
…into docs-url-prefix
Closes #303.
Everyone's local copy of
versionutils.py
already had the optioncontent_prefix
, which had to be set to e.g.ecosystem/finance
ordocumentation
. 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.