Updates the docs refer to 'govuk' namespace

As part of namespacing, we need to update the links the docs point to
so that they are still valid and do not break. We also needed to update
the examples to show how to use the new namespace.

docs/contributing/coding-standards/components.md

@@ -1,6 +1,6 @@
 # Components
 
-Find components in `src/components`.
+Find components in `src/govuk/components`.
 
 Components must use the `.govuk-` namespace.
 
@@ -20,8 +20,6 @@ Components must:
 
 Component folder and files should be singular, except in cases where they are more commonly used in groups, for example, radios, breadcrumbs and checkboxes.
 
-An example component exists in `src/components/component-example`.
-
 Use this as the basis for creating new components.
 
 The folder structure should be:

docs/contributing/coding-standards/css.md

@@ -466,4 +466,4 @@ We document SCSS using [SassDoc](http://sassdoc.com/file-level-annotations/). Th
 
 The syntax is used to generate a [SassDoc application](http://govuk-frontend-review.herokuapp.com/docs/) that documents SCSS in a readable format.
 
-See [colour.scss](../../../src/helpers/_colour.scss) for an example of SassDoc syntax.
+See [colour.scss](../../../src/govuk/helpers/_colour.scss) for an example of SassDoc syntax.

docs/contributing/coding-standards/js.md

@@ -104,7 +104,7 @@ Use default export over named export.
 
 ## Polyfilling
 
-If you need to support older browsers, import the necessary [polyfills](/src/vendor/polyfills) and they will be added to the environment when the feature is not supported.
+If you need to support older browsers, import the necessary [polyfills](/src/govuk/vendor/polyfills) and they will be added to the environment when the feature is not supported.
 
 For example, if you want to polyfill `addEventListener` for IE8, import the Event polyfills.
 

docs/contributing/coding-standards/nunjucks-api.md

@@ -6,7 +6,7 @@ To provide a level of consistency for developers we have standardised option nam
 
 The options (arguments) accepted by the component macro are specified in a `[component-name].yaml` file as `params`. Each option should have the following attributes: `name`, `type`, `required`, `description`.
 
-An option can additionally contain `params` that denotes nested items in the option (see [breadcrumbs component](https://github.com/alphagov/govuk-frontend/blob/master/src/components/breadcrumbs/breadcrumbs.yaml#L6)) and `isComponent: true` where the option is another component (see [checkboxes component](https://github.com/alphagov/govuk-frontend/blob/master/src/components/checkboxes/checkboxes.yaml#L11)).
+An option can additionally contain `params` that denotes nested items in the option (see [breadcrumbs component](https://github.com/alphagov/govuk-frontend/blob/master/src/govuk/components/breadcrumbs/breadcrumbs.yaml#L6)) and `isComponent: true` where the option is another component (see [checkboxes component](https://github.com/alphagov/govuk-frontend/blob/master/src/govuk/components/checkboxes/checkboxes.yaml#L11)).
 
 Component macro options are shipped as  `macro-options.json` in `package`.
 

docs/contributing/tasks.md

@@ -75,7 +75,7 @@ This task will:
 **`gulp compile:components`**
 
   This task will:
-  - compile all `src/components/componentName/componentName.njk` files to HTML files
+  - compile all `src/govuk/components/componentName/componentName.njk` files to HTML files
 
 **`gulp lint`**
 

docs/contributing/testing-and-linting.md

@@ -26,24 +26,24 @@ See [JavaScript Coding Standards](coding-standards/js.md#formatting-and-linting)
 
 We use [Jest](https://jestjs.io/), an automated testing platform with an assertion library, and [Puppeteer](https://pptr.dev/) that is used to control [headless Chrome](https://developers.google.com/web/updates/2017/04/headless-chrome).
 
-We test individual components and for instance global Sass files. See [all.test.js](../../src/all.test.js). for examples of global tests we run, and  [checkboxes.test.js](../../src/components/checkboxes/checkboxes.test.js) for an example of component tests.
+We test individual components and for instance global Sass files. See [all.test.js](../../src/govuk/all.test.js). for examples of global tests we run, and  [checkboxes.test.js](../../src/govuk/components/checkboxes/checkboxes.test.js) for an example of component tests.
 
 We aim to write the description of our tests in as "natural language" as possible, for instance "back-link component fails to render if the required fields are not included".
 
 ### Running individual tests
 You can run a subset of the test suite that only tests components by running:
 
-    `npm test -- src/components/button`
+    `npm test -- src/govuk/components/button`
 
 Note: There's a watch mode that keeps a testing session open waiting for changes that can be used with:
 
-    `npm test -- --watch src/components/button`
+    `npm test -- --watch src/govuk/components/button`
 
 ### Updating component snapshots
 [Snapshot tests](https://facebook.github.io/jest/docs/en/snapshot-testing.html) are used for preventing unintended changes - when the snapshot test runs, it  compares the previously captured snapshot to the current markup. For components, the snapshots are stored in `[component-name directory]/_snapshots_`.
 
 If a snapshot test fails, review the difference in the console. If the change is the correct change to make, run:
 
-`npm test -- -u src/components/button`
+`npm test -- -u src/govuk/components/button`
 
 This will update the snapshot file. Commit this file separately with a commit message that explains you're updating the snapshot file and an explanation of what caused the change.

docs/installation/compatibility.md

@@ -26,7 +26,7 @@ GOV.UK Frontend will:
 - no longer use `rem` for font sizes
 
 To turn on compatibility mode for all 3 legacy frameworks, add the following
-variables to your project's Sass file, above `@import "govuk-frontend/all"`:
+variables to your project's Sass file, above `@import "govuk-frontend/govuk/all"`:
 
 ```SCSS
 $govuk-compatibility-govukfrontendtoolkit: true;
@@ -42,7 +42,7 @@ If you are not using any of the legacy frameworks, you can still configure
 GOV.UK Frontend to use the old colour palette.
 
 Add the following variable to your project's Sass file, above
-`@import "govuk-frontend/all"`:
+`@import "govuk-frontend/govuk/all"`:
 
 ```scss
 $govuk-use-legacy-palette: true;

docs/installation/installing-with-npm.md

@@ -42,14 +42,14 @@ imports) if you want to override GOV.UK Frontend with your own styles.
 1. To import all components, add the below to your Sass file:
 
   ```SCSS
-  @import "node_modules/govuk-frontend/all";
+  @import "node_modules/govuk-frontend/govuk/all";
   ```
 
 2. To import an individual component (for example a button), add the below to
 your Sass file:
 
   ```SCSS
-  @import "node_modules/govuk-frontend/components/button/button";
+  @import "node_modules/govuk-frontend/govuk/components/button/button";
   ```
 
 ### Optional: Resolving SCSS import paths
@@ -82,7 +82,7 @@ to include add `includePaths` to it.
 After resolving the import paths you can import GOV.UK Frontend by using:
 
 ```SCSS
-@import "govuk-frontend/components/button/button";
+@import "govuk-frontend/govuk/components/button/button";
 ```
 
 ### Global Styles
@@ -93,14 +93,14 @@ This to avoid the risk of global styles conflicting with any pre-existing global
 
 Hovever, we do include some global styles in the [GOV.UK Prototype Kit](https://github.com/alphagov/govuk-prototype-kit-private-beta) to speed up prototyping.
 
-These [global styles](../../src/core/_global-styles.scss) are are not included by default in GOV.UK Frontend. To include these global styles in your app, you can set `$govuk-global-styles` variable to `true` before importing GOV.UK Frontend styles into your app:
+These [global styles](../../src/govuk/core/_global-styles.scss) are are not included by default in GOV.UK Frontend. To include these global styles in your app, you can set `$govuk-global-styles` variable to `true` before importing GOV.UK Frontend styles into your app:
 
 ```SCSS
 // application.scss
 
 $govuk-global-styles: true;
 
-@import "govuk-frontend/all";
+@import "govuk-frontend/govuk/all";
 ```
 
 ### Using GOV.UK Frontend with old frameworks
@@ -127,15 +127,15 @@ Note that GOV.UK Frontend does not initialise any scripts by default; all script
 
 ### Option 1: Include JavaScript
 
-Include the `node_modules/govuk-frontend/all.js` script on your page. You might wish to copy the file into your project or reference it from `node_modules`.
+Include the `node_modules/govuk-frontend/govuk/all.js` script on your page. You might wish to copy the file into your project or reference it from `node_modules`.
 
 To initialise all components, use the `initAll` function.
 
 JavaScript in GOV.UK Frontend requires HTML to be parsed first by the browser before it is initialised. Because of this, make sure you include the script before the closing `</body>` tag.
 Including the script elsewhere will stop components from functioning or displaying correctly.
 
 ```html
-    <script src="path-to-assets/govuk-frontend/all.js"></script>
+    <script src="path-to-assets/govuk-frontend/govuk/all.js"></script>
     <script>window.GOVUKFrontend.initAll()</script>
   </body>
 </html>
@@ -172,8 +172,6 @@ if ($radio) {
 }
 ```
 
-Some components such as the details or button components are initialised globally. If you want to see how these are initialised by default, see the [all.js](../../src/all.js) file.
-
 ### Option 2: Import JavaScript
 
 If you're using a bundler such as [Webpack](https://webpack.js.org/), use the `import` syntax to import all components. To initialise them, use the `initAll` function:
@@ -200,6 +198,12 @@ If you're using a bundler such as Webpack, use the `import` syntax to import a c
 import { Radios } from 'govuk-frontend'
 ```
 
+or
+
+```JS
+import Button from 'govuk-frontend/govuk/components/button/button'
+```
+
 If you're using a bundler such as [Browserify](http://browserify.org/), you may need to use the CommonJS `require`:
 
 
@@ -222,8 +226,6 @@ if ($radio) {
 }
 ```
 
-Some components such as the details or button components are initialised globally. If you want to see how these are initialised by default, see the [all.js](../../src/all.js) file.
-
 ### Polyfills
 A JavaScript polyfill provides functionality on older browsers or assistive technology that do not natively support it.
 
@@ -270,7 +272,7 @@ To use different asset paths, also complete the below step(s).
   // Include images from /application/assets/images and fonts from /application/assets/fonts
   $govuk-assets-path: '/application/assets';
 
-  @import "govuk-frontend/all";
+  @import "govuk-frontend/govuk/all";
   ```
 
   Example 2:
@@ -280,10 +282,10 @@ To use different asset paths, also complete the below step(s).
   $govuk-images-path: "/images/govuk-frontend/";
   $govuk-fonts-path: "/fonts/";
 
-  @import "govuk-frontend/all";
+  @import "govuk-frontend/govuk/all";
   ```
 
-2. Optional: You can also override the helpers used to generate the asset urls, for example if you are using sass-rails' asset-pipeline functionality. You can do this by setting `$govuk-image-url-function` to the name of the function(s) you wish to use. See `src/settings/_assets.scss` for more information and examples.
+2. Optional: You can also override the helpers used to generate the asset urls, for example if you are using sass-rails' asset-pipeline functionality. You can do this by setting `$govuk-image-url-function` to the name of the function(s) you wish to use. See `src/govuk/settings/_assets.scss` for more information and examples.
 
 ## Include CSS and JavaScript