Fix documentation links always pointing to master. #9217
Conversation
There was a problem hiding this comment.
Thanks for tackling this! The solution you propose does not solve all the issues around properly linking the tagged versions of the repo but I think we can change it slightly to make it work!
This is not urgent as @LysandreJik is on vacation (until Jan 4th) and I would very much like his review on this before merging.
docs/source/conf.py
Outdated
| @@ -27,7 +27,8 @@ | |||
| version = u'' | |||
| # The full version, including alpha/beta/rc tags | |||
| release = u'4.1.1' | |||
|
|
|||
| # Prefix link to always point to | |||
| extlinks = {'prefix_link': ('https://github.com/huggingface/transformers/blob/v4.1.1/%s', '')} | |||
There was a problem hiding this comment.
I think what @LysandreJik had in mind here was to use the release variable so each time we generate the docs on a given commit, the links are prefixed for that version.
But at the same time, it would also mean the master docs would always point to the latest release which is also something we don't want. So I think this line should be here but commented out, so that we uncomment it on the commit that is used to generate the docs of a specific version (with the proper tag using the release variable). This way when we regularly build the master doc at each PR, the links point to master, but when we make a release, we can just uncomment to build the links to the version released.
Does that make sense to you?
There was a problem hiding this comment.
Yes you're right it should point to master until release and duing release it must be changed, I have made changes accordingly and committed. Does this satisfy the requirements ?
There was a problem hiding this comment.
Yes, it's good! Thanks a lot! Let's wait for @LysandreJik to be back to merge this if you don't mind.
There was a problem hiding this comment.
Yeah @sgugger I don't mind. We can wait.
There was a problem hiding this comment.
In the meantime, there seems to be some styling problems so make sure to run make style on your branch, and one error in the doc building step (I've added a comment in marian.rst where I think it comes from).
There was a problem hiding this comment.
Yeah was checking those,thought of fixing them in the meantime. Thanks!
There was a problem hiding this comment.
Why does make style fix a lot of files which I haven't changed at all also when I try to use style_doc.py I get an error as here https://app.circleci.com/pipelines/github/huggingface/transformers/17685/workflows/f1f56681-8976-402a-95bd-387bd066ccb7/jobs/141134 that 10 files shoud be restyled ?! Am I missing something here ?
There was a problem hiding this comment.
If I just do black docs/source/conf.py also there are changes from single quote to double quote
docs/source/model_doc/marian.rst
Outdated
| - :prefix_link:`Fine-tune on TPU | ||
| <examples/seq2seq/builtin_trainer/train_distil_marian_enro_tpu.sh>` | ||
| - :prefix_link:`Fine-tune on GPU | ||
| <examples/seq2seq/builtin_trainer/train_distil_marian_enro.sh> | ||
| - :prefix_link:`Fine-tune on GPU with pytorch-lightning | ||
| <examples/seq2seq/distil_marian_no_teacher.sh>` |
There was a problem hiding this comment.
Those are all missing __ at the end and can probably fit in one line now.
There was a problem hiding this comment.
Hi, thanks for your work on this! I fixed the style and added a missing backtick so that all the tests pass.
Great work, thanks @sugeeth14!
|
Thanks for merging @LysandreJik but I want to know why the errors occurred when I ran |
What does this PR do?
This PR fixes documentation issue. The issue is that hyperlinks pointing to code file in the docs always point to the master.
Reference issue : #7988
I found extlinks more appropriate than rst_epilog
as mentioned in the original issue because hyperlink replacement is not possible with
rst_epilogStackoverflow issue reference : https://stackoverflow.com/questions/1227037/substitutions-inside-links-in-rest-sphinx
Although this fixes the issues as discussed I am unable to fix the issue in markup files which are https://huggingface.co/transformers/master/contributing.html and https://huggingface.co/transformers/master/notebooks.html
Please suggest if it is possible to do that as well.
Fixes #7988
@sgugger @LysandreJik