feature/update-docs #8
Conversation
mr-nick17
force-pushed
the
feature/3375-update-app-docs
branch
from
1d5ee16 to
c25d90d
Compare
GO_EXAMPLE.md
Outdated
| mv assets/data.go.new assets/data.go | ||
| ``` | ||
|
|
||
| Due to having distributed assets that are combined with `go-bindata`, we require the `get-renderer-version` and `fetch-renderer-version` tasks to ensure the version of `dp-renderer` as specified in `go.mod` is used. |
There was a problem hiding this comment.
Can't see a get-renderer-version task, have I missed it?
| debug: generate-debug | ||
| ``` | ||
|
|
||
| ## Config |
There was a problem hiding this comment.
Some kind of markdown syntax fail here - is it the code block above?
There was a problem hiding this comment.
I think it's a problem with git (probably not though 😅). It works fine locally and by switching to the rich-diff
|
|
||
| Example set up in `config.go`: | ||
|
|
||
| ```go |
There was a problem hiding this comment.
Similar here - maybe needs to be indented to pickup the formatting?
There was a problem hiding this comment.
As other comment - compare with 'display the rich diff'
GO_EXAMPLE.md
Outdated
|
|
||
| Example handler: | ||
|
|
||
| ```golang |
There was a problem hiding this comment.
Sometime you're using golang and sometimes go - can we be consistent?
README.md
Outdated
| ### Go library | ||
|
|
||
| `dis-design-system-go` also acts as a Go library which contains template helpers, model structs and components that can be used by the consuming frontend app to serve HTML consistently across the ONS website. To make use of the `go` rendering, you will need to install it within your `go` frontend app. | ||
|
|
||
| #### Installation | ||
|
|
||
| Other than `dis-design-system-go` itself, you will need a utility that can combine service-specific and `dis-design-system-go` assets. We currently use `go-bindata` for this process. From the consuming frontend app, run the following commands to install: | ||
|
|
||
| * `dis-design-system-go`: `go get github.com/ONSdigital/dis-design-system-go` | ||
|
|
||
| > You can specify a version of `dis-design-system-go` by appending a commit ID or semantic version number to this command. e.g., `go get github.com/ONSdigital/dis-design-system-go@d27f174` | ||
| * `go-bindata`: `go get github.com/kevinburke/go-bindata` | ||
|
|
||
| #### Instantiation | ||
|
|
||
| Assuming you have `go-bindata` set up to generate the relevant asset helper functions, you can instantiate the renderer with a default client (in this case, the default client is [`unrolled`](https://github.com/unrolled/render)). | ||
|
|
||
| ```go | ||
| rend := render.NewWithDefaultClient(asset.Asset, asset.AssetNames, cfg.PatternLibraryAssetsPath, cfg.SiteDomain) | ||
| ``` | ||
|
|
||
| You can also instantiate a `Render` struct without a default client by using `New()`. This requires a rendering client that fulfills the `Renderer` interface to be passed in as well. | ||
|
|
||
| ```go | ||
| rend := render.New(rendereringClient, patternLibPath, siteDomain) | ||
| ``` | ||
|
|
||
| #### Mapping data and building a page | ||
|
|
||
| When mapping data to a page model, you can use `NewBasePageModel` to instantiate a base page model with its `PatternLibraryAssetsPath` and `SiteDomain` properties auto-populated via the `Render` struct: | ||
|
|
||
| ```go | ||
| basePage := rendC.NewBasePageModel() | ||
| mappedPageData := mapper.CreateExamplePage(basePage) | ||
| ``` | ||
|
|
||
| In order to generate HTML from a page model and template, use `BuildPage`, passing in the `ResponseWriter`, mapped data, and the name of the template: | ||
|
|
||
| ```go | ||
| rend.BuildPage(w, mappedPageData, "name-of-template-file-without-extension") | ||
| ``` | ||
|
|
||
| If an error occurs during page build, either because of an incorrect template name or incorrect data mapping, `dp-renderer` will write an error via an `errorResponse` struct. | ||
|
|
||
| ## Using design patterns or components in your service | ||
|
|
||
| See [PATTERNS](PATTERNS.md) for details. | ||
|
|
||
| ## Worked example | ||
|
|
||
| See the [go example](GO_EXAMPLE.md) guide for a worked example. This guide can also be used to support migrating from `dp-renderer` and `dp-design-system` to `dis-design-system-go`. | ||
|
|
There was a problem hiding this comment.
This looks to duplicate a lot of GO_EXAMPLE.
There was a problem hiding this comment.
Restructured and created a migration doc
Pedantism makes the world go round 😄. I've had another think and restructured the docs. I was trying to avoid having another migration doc that explains what the README does and subsequently doesn't get updated but I take your point that it might be clearer. Hopefully the proposal is succinct enough for a dev to migrate an app; while the go_example provides enough rich detail to setup a greenfield app |
mr-nick17
force-pushed
the
feature/3375-update-app-docs
branch
from
0a0610a to
e765578
Compare
mr-nick17
force-pushed
the
feature/3375-update-app-docs
branch
from
b34bec0 to
cfc4dff
Compare
What
Docs:
readmepatternsreadme fromdp-rendererHow to review
Sense check
P.S. Audit is fixed in separate PR #7
Who can review
!me