Create demo app and move documentation to sub-app #244

edwardhorsford · 2016-08-22T16:22:23Z

This is a newer version of #158.

This PR moves documentation and examples outside of app and in to a new sub-app called docs. This gives us a more consistent place to put documentation, and means our upgrade path is easier - users upgrading via copying app will now be able to get up to date documentation.

This PR also introduces a new documentation 'home' - the intention being we can push this to heroku and have a single place we can point people at to get the kit and docs, etc.

You can play with it here: https://prototype-kit-documentation2.herokuapp.com

Fixes #151

Changes:

Move docs and examples in to sub-app /docs/
New docs start page which links to everything.
Uses github API to get the url to the zip of the latest release - easier than linking to github.
Renders markdown files as html - markdown will still work and link in Github though (though we may not need this).
Introduces a config var to enable docs or not.
Introduces a env var to redirect the root to docs - this means we can deploy to govuk-prototype-kit.herokuapp.com and have the docs be the primary page.
Change to npm module nunjucks from express-nunjucks, as it didn't seem to correctly support sub-applications.

Things that aren't finished:

The tutorials and examples page is a bit of a mess. There's too many things. Potentially tutorials and examples could be two separate pages, but there's a bit of overlap between them.
I think the end navigation should be `Download | Getting started | Tutorials and examples | Github | About - I haven't done this yet though.

NB: I'd expect this to be a major version change.

joelanman · 2016-08-22T19:13:21Z

docs/views/includes/prototype_kit_navigation.html

+        <li><a href="/docs/install">Install</a></li>
+        <li><a href="/docs/tutorials-and-examples">Tutorials and examples</a></li>
+        <li><a href="/docs/about">About</a></li>
+        <li><a href="https://github.com/alphagov/govuk_prototype_kit">Github</a></li>


Github > GitHub

joelanman · 2016-08-22T19:15:31Z

nice! thanks for all this work

Just going through it - but a quick note: I think the copy under the headings on the home page could be clearer - what do you think about getting a content person on it?

joelanman · 2016-08-22T20:04:46Z

docs/assets/sass/docs.scss

+		@extend .heading-small;
+	}
+
+	code {


can't remember who wrote this originally, but why isnt the code block just @extend .code?

Not sure, but you need the other things for it to display correctly I think. I'm still not happy with the code styling though.

joelanman · 2016-08-22T20:19:50Z

In the existing docs, you can jump straight to Run the kit, which we've seen in training to be useful. Don't think you can jump to that in the new docs, it's just the last page of "Install the kit". Do you think we can link to it from somewhere?

joelanman · 2016-08-22T20:23:04Z

docs/documentation_routes.js

+});
+
+router.get('/install', function (req, res) {
+  console.log('hi');


joelanman · 2016-08-22T20:24:16Z

look like it all needs to go through the linter - there are some missing 'var' declarations, semi-colons to be removed. Try a rebase, then npm test

joelanman · 2016-08-22T20:48:45Z

docs/documentation_routes.js

+  res.render("install_template", {"document": html});
+});
+
+// Examples - exampes post here


joelanman · 2016-08-22T21:06:27Z

can docs/documentation_routes.js just be docs/routes.js?

joelanman · 2016-08-22T21:51:33Z

on the / index page, we should probably link to the new docs app on heroku, rather than docs on github

joelanman · 2016-08-22T22:00:35Z

maybe we should use Express 4 sub apps, as they seem designed for this situation: http://www.therightcode.net/differences-between-express-3-and-express-4/

joelanman · 2016-08-22T22:02:54Z

lib/utils.js

+exports.matchRoutes = function(req, res) {
+
+  var path = (req.params[0]);
+  console.log('path is', path);


gemmaleigh · 2016-08-23T08:29:52Z

Hi @edwardhorsford to try and help out a little here before you try to rebase against master - I've added a commit where I add standard as a dependency and start linting the files in this codebase.

Hopefully it will help make the rebase with master a little less painful. That commit can always be removed later.

To continue with linting, run npm test, hope that helps!

joelanman · 2016-08-23T10:07:24Z

lib/utils.js

+  request = require('sync-request')
+
+// Variables
+var releaseUrl = null

 /**


these comments belong to the basicAuth function, so they need to be moved back to being above it

edwardhorsford · 2016-09-28T09:35:09Z

@joelanman I'm intentionally giving the files distinctive names so that people don't accidentally start editing the wrong one when using quick-search.

Not sure about the differences between the different apps - but the current ones seem to work ok to me. What are the benefits of switching?

joelanman · 2016-09-28T14:08:38Z

@edwardhorsford I'm not sure how scalable it is to avoid duplicate filenames - for example we already have multiple index.html. In quick search you can include the name of the parent folder (giving you the same outcome as the longer name), and it shows the parent folder in the search too.

There's value in using the Express 4 app approach because thats the standard documented way to do it - development in the future would be easier as people can consult those docs, and other modules might expect that standard approach. But if you're happy this approach works we could always cross that bridge if we came to it.

edwardhorsford · 2016-10-12T13:45:00Z

I'm not sure what problem there is for it to have a unique name in this case. It's a mistake I personally made multiple times. The current name is descriptive for what the file is. I'm not suggesting a blanket rule of avoiding duplicates, but having of having a descriptive name in this case for a file users will likely be editing frequently.

I'm not familiar with the other approach for apps, and the current one works. If you'd like to tackle it, great, else perhaps we release and raise an issue to consider it later?

This commit can be removed later as these files have already been linted on master, but it may well help with the rebase. I’ve made a start on linting here, to continue with linting run `npm test`, there are still errors in server.js. utils.js and documentation_routes.js.

- Docs should have its own JS file (which now includes the latest from toolkit) - Docs images should be copied into their own folder in /public

robinwhittleton · 2016-10-13T11:09:05Z

OK, @gemmaleigh and I have just reviewed this and it looks good. We’ve made a few more changes after @edwardhorsford’s work to sort out the docs assets. Happy to merge, and we can deal with any docs updates after that.

Breaking changes: - #244 Migrate documentation into a seperate application All changes: - Bump all GOV.UK assets to their latest versions - Remove duplicate GOV.UK assets copied to the app - #241 Warn against using the prototype kit to build production services - #268 Automatically keep the latest release branch up to date. This can be used to update the kit - #270 Add a new stylesheet for the unbranded layout to fix font issues - #257 Make CSS output easier to debug (with sourcemaps) - #237 Make links with role="button" behave like buttons - #224 Lint the prototype kit’s codebase using Standard. This only applies to the kit’s codebase - there’s no requirement for your app to meet this

Breaking changes: - #244 Migrate documentation into a separate application All changes: - Bump all GOV.UK assets to their latest versions - Remove duplicate GOV.UK assets copied to the app - #241 Warn against using the prototype kit to build production services - #268 Automatically keep the latest release branch up to date. This can be used to update the kit - #270 Add a new stylesheet for the unbranded layout to fix font issues - #257 Make CSS output easier to debug (with sourcemaps) - #237 Make links with role="button" behave like buttons - #224 Lint the prototype kit’s codebase using Standard. This only applies to the kit’s codebase - there’s no requirement for your app to meet this

edwardhorsford added the in progress label Aug 22, 2016

edwardhorsford changed the title ~~Create demo app and move documentation to sub-ab~~ Create demo app and move documentation to sub-app Aug 22, 2016

joelanman reviewed Aug 22, 2016
View reviewed changes

docs/documentation_routes.js

});

router.get('/install', function (req, res) {

console.log('hi');

Copy link

Contributor

joelanman Aug 22, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

delete?

joelanman reviewed Aug 22, 2016
View reviewed changes

docs/documentation_routes.js

res.render("install_template", {"document": html});

});

// Examples - exampes post here

Copy link

Contributor

joelanman Aug 22, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo

joelanman reviewed Aug 22, 2016
View reviewed changes

lib/utils.js

exports.matchRoutes = function(req, res) {

var path = (req.params[0]);

console.log('path is', path);

Copy link

Contributor

joelanman Aug 22, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

delete?

joelanman reviewed Aug 23, 2016
View reviewed changes

edwardhorsford force-pushed the docs_app branch from c340308 to 55977bf Compare August 24, 2016 13:15

gemmaleigh mentioned this pull request Sep 21, 2016

DO NOT MERGE: Split documentation in to sub-app #158

Closed

edwardhorsford mentioned this pull request Oct 12, 2016

Feature Request: 'Latest' release branch creating as part of release process #259

Closed

edwardhorsford added 4 commits October 13, 2016 11:07

First pass at creating separate documentation app

39747e7

Add config to enable/disable docs and promo mode

5c1ad2f

Add install page and ability to get zip of latest release

95fed51

Move examples to /docs, create about and community pages

1e18201

edwardhorsford and others added 6 commits October 13, 2016 11:07

Render markdown files as html, style them

e1e98dd

Set up auto-routing for markdown files

34e7017

Minor text tweaks, rename nav, update tutorials page with links

4156a7e

Link to individual tutorial pages instead of start

68dbbea

Minor style tweaks and fixing other errors after PR review

2f56c53

robinwhittleton force-pushed the docs_app branch from 876d950 to 2f56c53 Compare October 13, 2016 10:14

Robin Whittleton added 2 commits October 13, 2016 11:33

Fix link to kit requirements page in docs

e0193d5

Make docs more separate from the rest of the app

cd45614

- Docs should have its own JS file (which now includes the latest from toolkit) - Docs images should be copied into their own folder in /public

robinwhittleton merged commit 3ed3730 into master Oct 13, 2016

robinwhittleton deleted the docs_app branch October 13, 2016 11:09

gemmaleigh removed the in progress label Oct 13, 2016

robinwhittleton mentioned this pull request Oct 13, 2016

v4.0.0 #280

Merged

edwardhorsford mentioned this pull request Nov 2, 2020

Simplify download link logic #953

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Create demo app and move documentation to sub-app #244

Create demo app and move documentation to sub-app #244

edwardhorsford commented Aug 22, 2016

joelanman Aug 22, 2016

edwardhorsford Sep 22, 2016

joelanman commented Aug 22, 2016

joelanman Aug 22, 2016 •

edited

Loading

edwardhorsford Sep 22, 2016

joelanman commented Aug 22, 2016

joelanman Aug 22, 2016

joelanman commented Aug 22, 2016

joelanman Aug 22, 2016

joelanman commented Aug 22, 2016 •

edited by edwardhorsford

Loading

joelanman commented Aug 22, 2016

joelanman commented Aug 22, 2016

joelanman Aug 22, 2016

gemmaleigh commented Aug 23, 2016

joelanman Aug 23, 2016

edwardhorsford commented Sep 28, 2016

joelanman commented Sep 28, 2016

edwardhorsford commented Oct 12, 2016

robinwhittleton commented Oct 13, 2016

Create demo app and move documentation to sub-app #244

Create demo app and move documentation to sub-app #244

Conversation

edwardhorsford commented Aug 22, 2016

joelanman Aug 22, 2016

Choose a reason for hiding this comment

edwardhorsford Sep 22, 2016

Choose a reason for hiding this comment

joelanman commented Aug 22, 2016

joelanman Aug 22, 2016 • edited Loading

Choose a reason for hiding this comment

edwardhorsford Sep 22, 2016

Choose a reason for hiding this comment

joelanman commented Aug 22, 2016

joelanman Aug 22, 2016

Choose a reason for hiding this comment

joelanman commented Aug 22, 2016

joelanman Aug 22, 2016

Choose a reason for hiding this comment

joelanman commented Aug 22, 2016 • edited by edwardhorsford Loading

joelanman commented Aug 22, 2016

joelanman commented Aug 22, 2016

joelanman Aug 22, 2016

Choose a reason for hiding this comment

gemmaleigh commented Aug 23, 2016

joelanman Aug 23, 2016

Choose a reason for hiding this comment

edwardhorsford commented Sep 28, 2016

joelanman commented Sep 28, 2016

edwardhorsford commented Oct 12, 2016

robinwhittleton commented Oct 13, 2016

joelanman Aug 22, 2016 •

edited

Loading

joelanman commented Aug 22, 2016 •

edited by edwardhorsford

Loading