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>
This commit is contained in:
Sylvain Gugger 2021-12-15 14:40:47 -05:00 committed by GitHub
parent c40ecfd740
commit 459677aebe
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 51 additions and 105 deletions

View File

@ -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

View File

@ -442,109 +442,29 @@ Known caveats:
doing this yourself: `--sharded_ddp "zero_dp_3 auto_wrap"`.
### DeepSpeed
Sections that were moved:
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).
[ <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>
]