Steal first version of tech docs from teacher training api#1172
Steal first version of tech docs from teacher training api#1172
Conversation
|
Created review app at https://ecf-review-pr-1172.london.cloudapps.digital |
|
Smoke tests passed against the review app. |
|
|
||
| get "/how-to-set-up-your-programme", to: "step_by_step#show", as: :step_by_step | ||
|
|
||
| get "/assets/govuk/assets/fonts/:name.:extension", to: redirect("/api-reference/assets/govuk/assets/fonts/%{name}.%{extension}") |
There was a problem hiding this comment.
not sure we want this? every asset will require an extra request assuming it's not cached. I feel like this is a workaround and doesn't solve the actual problem we have introduced.
There was a problem hiding this comment.
The problem is that the gem govuk_tech_docs hard-codes its assets to be in /assets/govuk/assets/, and I am not sure it's a good place for something that's a small part of our application.
govuk_tech_docs in general doesn't seem to believe it should be just a small part of an application. But I think it is a pretty good idea to have the tech docs be part of what we release, and this seemed like the simplest solution. I guess we could make it a separate mini-service in paas, but that would require a lot of dev ops fun :/
There was a problem hiding this comment.
We could get rid of it when alphagov/tech-docs-gem#197 goes in, or something similar to it.
2 participants
Ticket and context
Ticket: https://dfedigital.atlassian.net/browse/CPDTP-477
I had a little dig, and it seemed to me that what the docs looked in the ticket was eerily similar to what TeacherTraining API were doing. Which is using a gem to generate their documentation.
Vast majority of changes are caused by a different way of automatically presenting API operations - I cut out everything we stole from Apply for Teacher Training, and brought in everything from TeacherTraining API.
The proof of the pudding is in the eating, so dig in - https://ecf-review-pr-1172.london.cloudapps.digital/api-reference
The technical gist of how the docs are handled: We use
govuk_tech_docsto harness power ofmiddlemanto generate a static site from the stuff we put indocsdirectory. We output that static site intopublic/api-referenceat build time - so when we run our application, it is served from/api-referencepath. One drawback of it which I haven't found a solution to is that running percy and / or axe on it seems harder. Since it would require the static site to be built before we ran the feature specs :/ I added some basic smoke tests but maybe they are not quite enough. Open to suggestions.Getting that
api-referencepath to work was harder than expected, cause the gem is a bit opinionated - I needed to override some methods generating headings on left hand side, because without it they thought everything should be in one big family underapi-reference.Open to suggestions of what I missed :)