PoC for conserving old links (#14754)

* PoC for conserving old links

* Do the same for other links

* remap the redirects section

* add instructions on how to move sections

* improve
Co-authored-by: Stas Bekman <stas@stason.org>

docs/README.md

@@ -86,6 +86,32 @@ It should build the static app that will be available under `/docs/_build/html`
 Accepted files are reStructuredText (.rst) and Markdown (.md). Create a file with its extension and put it
 in the source directory. You can then link it to the toc-tree by putting the filename without the extension.
 
+## Renaming section headers and moving sections
+
+It helps to keep the old links working when renaming section header and/or moving sections from one document to another. This is because the old links are likely to be used in Issues, Forums and Social media and it'd be make for a much more superior user experience if users reading those months later could still easily navigate to the originally intended information.
+
+Therefore we simply keep a little map of moved sections at the end of the document where the original section was. The key is to preserve the original anchor.
+
+So if you renamed a section from: "Section A" to "Section B", then you can add at the end of the file:
+
+```
+Sections that were moved:
+
+[ <a href="#section-b">Section A</a><a id="section-a"></a> ]
+```
+and of course if you moved it to another file, then:
+
+```
+Sections that were moved:
+
+[ <a href="../new-file#section-b">Section A</a><a id="section-a"></a> ]
+```
+
+Use the relative style to link to the new file so that the versioned docs continue to work.
+
+For an example of a rich moved sections set please see the very end of [the Trainer doc](https://github.com/huggingface/transformers/blob/master/docs/source/main_classes/trainer.mdx).
+
+
 ## Preview the documentation in a pull request
 
 Once you have made your pull request, you can check what the documentation will look like after it's merged by

docs/source/main_classes/trainer.mdx

@@ -442,109 +442,29 @@ Known caveats:
   doing this yourself: `--sharded_ddp "zero_dp_3 auto_wrap"`.
 
 
-### DeepSpeed
-
-
-Moved to [Trainer DeepSpeed integration](deepspeed#trainer-deepspeed-integration).
-
-
-#### Installation
-
-Moved to [Installation](deepspeed#deepspeed-installation).
-
-
-#### Deployment with multiple GPUs
-
-Moved to [Deployment with multiple GPUs](deepspeed#deepspeed-multi-gpu).
-
-
-#### Deployment with one GPU
-
-Moved to [Deployment with one GPU](deepspeed#deepspeed-one-gpu).
-
-
-#### Deployment in Notebooks
-
-Moved to [Deployment in Notebooks](deepspeed#deepspeed-notebook).
-
-
-#### Configuration
-
-Moved to [Configuration](deepspeed#deepspeed-config).
-
-
-#### Passing Configuration
-
-Moved to [Passing Configuration](deepspeed#deepspeed-config-passing).
-
-
-#### Shared Configuration
-
-Moved to [Shared Configuration](deepspeed#deepspeed-config-shared).
-
-#### ZeRO
-
-Moved to [ZeRO](deepspeed#deepspeed-zero).
-
-##### ZeRO-2 Config
-
-Moved to [ZeRO-2 Config](deepspeed#deepspeed-zero2-config).
-
-##### ZeRO-3 Config
-
-Moved to [ZeRO-3 Config](deepspeed#deepspeed-zero3-config).
-
-
-#### NVMe Support
-
-Moved to [NVMe Support](deepspeed#deepspeed-nvme).
-
-##### ZeRO-2 vs ZeRO-3 Performance
-
-Moved to [ZeRO-2 vs ZeRO-3 Performance](deepspeed#deepspeed-zero2-zero3-performance).
-
-##### ZeRO-2 Example
-
-Moved to [ZeRO-2 Example](deepspeed#deepspeed-zero2-example).
-
-##### ZeRO-3 Example
-
-Moved to [ZeRO-3 Example](deepspeed#deepspeed-zero3-example).
-
-
-#### Optimizer and Scheduler
-
-##### Optimizer
-
-Moved to [Optimizer](deepspeed#deepspeed-optimizer).
-
-
-##### Scheduler
-
-Moved to [Scheduler](deepspeed#deepspeed-scheduler).
-
-#### fp32 Precision
-
-Moved to [fp32 Precision](deepspeed#deepspeed-fp32).
-
-#### Automatic Mixed Precision
-
-Moved to [Automatic Mixed Precision](deepspeed#deepspeed-amp).
-
-#### Batch Size
-
-Moved to [Batch Size](deepspeed#deepspeed-bs).
-
-#### Gradient Accumulation
-
-Moved to [Gradient Accumulation](deepspeed#deepspeed-grad-acc).
-
-
-#### Gradient Clipping
-
-Moved to [Gradient Clipping](deepspeed#deepspeed-grad-clip).
-
-
-#### Getting The Model Weights Out
-
-Moved to [Getting The Model Weights Out](deepspeed#deepspeed-weight-extraction).
+Sections that were moved:
+
+[ <a href="./deepspeed#deepspeed-trainer-integration">DeepSpeed</a><a id="deepspeed"></a>
+| <a href="./deepspeed#deepspeed-installation">Installation</a><a id="installation"></a>
+| <a href="./deepspeed#deepspeed-multi-gpu">Deployment with multiple GPUs</a><a id="deployment-with-multiple-gpus"></a>
+| <a href="./deepspeed#deepspeed-one-gpu">Deployment with one GPU</a><a id="deployment-with-one-gpu"></a>
+| <a href="./deepspeed#deepspeed-notebook">Deployment in Notebooks</a><a id="deployment-in-notebooks"></a>
+| <a href="./deepspeed#deepspeed-config">Configuration</a><a id="configuration"></a>
+| <a href="./deepspeed#deepspeed-config-passing">Passing Configuration</a><a id="passing-configuration"></a>
+| <a href="./deepspeed#deepspeed-config-shared">Shared Configuration</a><a id="shared-configuration"></a>
+| <a href="./deepspeed#deepspeed-zero">ZeRO</a><a id="zero"></a>
+| <a href="./deepspeed#deepspeed-zero2-config">ZeRO-2 Config</a><a id="zero-2-config"></a>
+| <a href="./deepspeed#deepspeed-zero3-config">ZeRO-3 Config</a><a id="zero-3-config"></a>
+| <a href="./deepspeed#deepspeed-nvme">NVMe Support</a><a id="nvme-support"></a>
+| <a href="./deepspeed#deepspeed-zero2-zero3-performance">ZeRO-2 vs ZeRO-3 Performance</a><a id="zero-2-vs-zero-3-performance"></a>
+| <a href="./deepspeed#deepspeed-zero2-example">ZeRO-2 Example</a><a id="zero-2-example"></a>
+| <a href="./deepspeed#deepspeed-zero3-example">ZeRO-3 Example</a><a id="zero-3-example"></a>
+| <a href="./deepspeed#deepspeed-optimizer">Optimizer</a><a id="optimizer"></a>
+| <a href="./deepspeed#deepspeed-scheduler">Scheduler</a><a id="scheduler"></a>
+| <a href="./deepspeed#deepspeed-fp32">fp32 Precision</a><a id="fp32-precision"></a>
+| <a href="./deepspeed#deepspeed-amp">Automatic Mixed Precision</a><a id="automatic-mixed-precision"></a>
+| <a href="./deepspeed#deepspeed-bs">Batch Size</a><a id="batch-size"></a>
+| <a href="./deepspeed#deepspeed-grad-acc">Gradient Accumulation</a><a id="gradient-accumulation"></a>
+| <a href="./deepspeed#deepspeed-grad-clip">Gradient Clipping</a><a id="gradient-clipping"></a>
+| <a href="./deepspeed#deepspeed-weight-extraction">Getting The Model Weights Out</a><a id="getting-the-model-weights-out"></a>
+]