From 9a7c6cc61a10dbd9d6613639292b7a83ad948b09 Mon Sep 17 00:00:00 2001
From: svlandeg <sofie.vanlandeghem@gmail.com>
Date: Wed, 9 Sep 2020 14:47:32 +0200
Subject: [PATCH] references to usage page on layers and architectures

---
 website/docs/usage/layers-architectures.md | 14 ++++++++------
 website/docs/usage/processing-pipelines.md | 17 +++++++++--------
 2 files changed, 17 insertions(+), 14 deletions(-)

diff --git a/website/docs/usage/layers-architectures.md b/website/docs/usage/layers-architectures.md
index db1abda46..1e39ffb9a 100644
--- a/website/docs/usage/layers-architectures.md
+++ b/website/docs/usage/layers-architectures.md
@@ -415,11 +415,11 @@ with Model.define_operators({">>": chain}):
     model.initialize(X=input_sample, Y=output_sample)
 ```
 
-The built-in
-[pipeline components](http://localhost:8000/usage/processing-pipelines) in spaCy
-ensure that their internal models are always initialized with appropriate sample
-data. In this case, `X` is typically a `List` of `Doc` objects, while `Y` is a
-`List` of 1D or 2D arrays, depending on the specific task.
+The built-in [pipeline components](/usage/processing-pipelines) in spaCy ensure
+that their internal models are always initialized with appropriate sample data.
+In this case, `X` is typically a `List` of `Doc` objects, while `Y` is a `List`
+of 1D or 2D arrays, depending on the specific task. This functionality is
+triggered when [`nlp.begin_training`](/api/language#begin_training) is called.
 
 ### Dropout and normalization {#drop-norm}
 
@@ -443,7 +443,7 @@ with Model.define_operators({">>": chain}):
     model.initialize(X=input_sample, Y=output_sample)
 ```
 
-## Create new components {#components}
+## Create new trainable components {#components}
 
 <!-- TODO:
 
@@ -452,6 +452,8 @@ with Model.define_operators({">>": chain}):
 
 Example: relation extraction component (implemented as project template)
 
+Avoid duplication with usage/processing-pipelines#trainable-components ?
+
 -->
 
 ![Diagram of a pipeline component with its model](../images/layers-architectures.svg)
diff --git a/website/docs/usage/processing-pipelines.md b/website/docs/usage/processing-pipelines.md
index a875df29c..3d756215f 100644
--- a/website/docs/usage/processing-pipelines.md
+++ b/website/docs/usage/processing-pipelines.md
@@ -1028,11 +1028,11 @@ plug fully custom machine learning components into your pipeline. You'll need
 the following:
 
 1. **Model:** A Thinc [`Model`](https://thinc.ai/docs/api-model) instance. This
-   can be a model using [layers](https://thinc.ai/docs/api-layers) implemented
-   in Thinc, or a [wrapped model](https://thinc.ai/docs/usage-frameworks)
-   implemented in PyTorch, TensorFlow, MXNet or a fully custom solution. The
-   model must take a list of [`Doc`](/api/doc) objects as input and can have any
-   type of output.
+   can be a model using implemented in
+   [Thinc](/usage/layers-architectures#thinc), or a
+   [wrapped model](/usage/layers-architectures#frameworks) implemented in
+   PyTorch, TensorFlow, MXNet or a fully custom solution. The model must take a
+   list of [`Doc`](/api/doc) objects as input and can have any type of output.
 2. **Pipe subclass:** A subclass of [`Pipe`](/api/pipe) that implements at least
    two methods: [`Pipe.predict`](/api/pipe#predict) and
    [`Pipe.set_annotations`](/api/pipe#set_annotations).
@@ -1078,8 +1078,9 @@ _first_ create a `Model` from a [registered architecture](/api/architectures),
 validate its arguments and _then_ pass the object forward to the component. This
 means that the config can express very complex, nested trees of objects – but
 the objects don't have to pass the model settings all the way down to the
-components. It also makes the components more **modular** and lets you swap
-different architectures in your config, and re-use model definitions.
+components. It also makes the components more **modular** and lets you
+[swap](/usage/layers-architectures#swap-architectures) different architectures
+in your config, and re-use model definitions.
 
 ```ini
 ### config.cfg (excerpt)
@@ -1134,7 +1135,7 @@ loss is calculated and to add evaluation scores to the training output.
 For more details on how to implement your own trainable components and model
 architectures, and plug existing models implemented in PyTorch or TensorFlow
 into your spaCy pipeline, see the usage guide on
-[layers and model architectures](/usage/layers-architectures#components).
+[layers and model architectures](/usage/layers-architectures).
 
 </Infobox>