Unverified Commit 459677ae authored by Sylvain Gugger's avatar Sylvain Gugger Committed by GitHub
Browse files

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: default avatarStas Bekman <stas@stason.org>
parent c40ecfd7
...@@ -86,6 +86,32 @@ It should build the static app that will be available under `/docs/_build/html` ...@@ -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 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. 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 ## 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 Once you have made your pull request, you can check what the documentation will look like after it's merged by
......
...@@ -442,109 +442,29 @@ Known caveats: ...@@ -442,109 +442,29 @@ Known caveats:
doing this yourself: `--sharded_ddp "zero_dp_3 auto_wrap"`. doing this yourself: `--sharded_ddp "zero_dp_3 auto_wrap"`.
### DeepSpeed Sections that were moved:
[ <a href="./deepspeed#deepspeed-trainer-integration">DeepSpeed</a><a id="deepspeed"></a>
Moved to [Trainer DeepSpeed integration](deepspeed#trainer-deepspeed-integration). | <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>
#### Installation | <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>
Moved to [Installation](deepspeed#deepspeed-installation). | <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>
#### Deployment with multiple GPUs | <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>
Moved to [Deployment with multiple GPUs](deepspeed#deepspeed-multi-gpu). | <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>
#### Deployment with one GPU | <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>
Moved to [Deployment with one GPU](deepspeed#deepspeed-one-gpu). | <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>
#### Deployment in Notebooks | <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>
Moved to [Deployment in Notebooks](deepspeed#deepspeed-notebook). | <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>
]
#### 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).
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment