Convert Trainer doc page to MarkDown #14753
Conversation
|
|
||
|
|
||
| Moved to [Trainer DeepSpeed integration](deepspeed#trainer-deepspeed-integration). | ||
|
|
There was a problem hiding this comment.
The intention was to preserve old links. so if someone on another site/forum linked to a specific section the user following this link will be able to find the new location after the move.
If you remove it, the anchor will fail and the user will get the top of the page and won't even know about that main: moved to ...
One easy way to fix this on the web server level is to create a redirect file which matches the old link with the anchor and redirects it to a new location, .e.g;
https://huggingface.co/docs/transformers/main_classes/trainer#deepspeed| https://huggingface.co/docs/transformers/master/en/main_classes/trainer#deepspeed-trainer-integration
... same for all other redirects ...
we already have a redirect rule from .html to non-html link, so these need to be added there.
It appears hf.co is running on nginx webserver, so need to look up the format for redirects on that server.
then we can nuke those "poor man's redirects" in the doc itself.
There was a problem hiding this comment.
should we discuss this on #doc-frontend?
There was a problem hiding this comment.
nginx does not see anchor links, this is a purely client-side element
There was a problem hiding this comment.
Too bad then. In this case, how about we just leave the HTML anchors and remove all visible content? A user that tries a "dead" link will then see "Moved to [Trainer DeepSpeed integration]" and can then easily find their way from there.
There was a problem hiding this comment.
Thank you, @julien-c, for sharing that. Indeed the browser doesn't send the anchor part to the server :(
That means we can't do the redirect in the rules file :(
It's your call Sylvain, if you prefer clean and neat over supporting existing links then please remove all but the first one.
Alternatively, we could discuss and agree on a general policy - when we rename headers or move content to a different file, do we support old links or not and at what cost. And depending on the outcome of that discussion then this decision about the current question can be made.
There was a problem hiding this comment.
In this case, how about we just leave the HTML anchors and remove all visible content? A user that tries a "dead" link will then see "Moved to [Trainer DeepSpeed integration]" and can then easily find their way from there.
If it works that would be great. Could you do a single link mockup to see what you mean exactly?
Something like:
<h3><a href="#deepspeed"></a>DeepSpeed</h3>
<p>Moved to <a href="/docs/transformers/master/en/main_classes/trainer#deepspeed-trainer-integration">deepspeed-trainer-integration</a>.</p>
but add it to a non-visible class?
There was a problem hiding this comment.
I'll open a fresh PR with an example to discuss this and merge this one in the meantime to fix the related issue :-)
| @@ -46,4 +46,4 @@ jobs: | |||
|
|
|||
| - name: Make documentation | |||
| run: | | |||
| doc-builder build transformers ./transformers/docs/source | |||
| doc-builder build transformers ./docs/source | |||
There was a problem hiding this comment.
An error actually made me realize the path was wrong all along 🤦
What does this PR do?
The
doc-builderonly resolvesrefwhen they point to sections in the same page, so this PR fixes #14730 by converting the doc page to MarkDown and fixing all links. In passing, it removes mention of theTFTrainerwhich is now deprecated.