Post Reply 
Author [How to] Run the documentation stack locally
fbernardo
AT core team member

Find all posts by this user
Quote this message in a reply
Default  22 November 2013 14:34
Un updated version of the installation instruction is available later in this thread.

This article explains how to get the AT user manual to run locally so that you can test your articles, snippets and samples before pushing anything to Github.

Prerequisite

You need to fork and update to the latest version those repos:

1. documentation-code
2. usermanual
3. snippets.ariatemplates.com

you need the npm-shrinkwrap.json file to copy/paste it inside usermanual folder, same level as package.json


.json  npm-shrinkwrap.json (Size: 15.79 KB / Downloads: 15)

Static content

This configuration allows you to display articles, snippets and samples locally.

1. Inside usermanual repo (same level of package.json) copy/paste npm-shrinkwrap.json file and npm install the dependencies.

2. Generating the documentation, i.e. converting all md files to html ones, is done by typing node build.js latest at the root of the usermanual repo. You need to do that every time you modify an article.

3. To test the documentation, run node test. This launches a local web server on http://localhost:8000 from which you can display the user manual. Of course, this server only handles links in /usermanual, do not expect all the web site to run, but it will serve you all your local version of articles, samples and snippets.

Snippets & Samples

Snippets are included in articles using <script> tags. Inside the src attribute you can see a placeholder %SNIPPETS_SERVER_URL% prefixing the snippets path. This placeholder is automatically replaced by the application and it will point to the proper URL:

- http://localhost:3000 if node environment variable is explicitly set to development;
- http://snippets.ariatemplates.com if node environment variable is empty or set to production;

To change the node environment variable:

- export NODE_ENV="production" or export NODE_ENV="" to set it equals to production;
- export NODE_ENV="development" to set it to development;

Normally, if you did not change it, your environment var should be empty, thus meaning production mode, so you'll need to set it to work in development mode. This mode is also useful when you are working locally because it doesn't use the cache.

The server fetches the code, colorize it and send it back. To run the snippets server you need to specify the documentation-code folder path:

1. From your snippets.ariatemplates.com repo: node server.js --dp path_to_documentation-code (e.g. node server.js --dp G:/github/fab-b_documentation-code)

2. Check that you launched usermanual server (as explained before)

3. Modify your sample/snippet, hit refresh on your browser and see the changes



At this point, both snippets and samples should be running from your local repositories. When process environment is on development mode the AT framework is downloaded from the CDN.
(This post was last modified: 15 April 2014 13:33 by flongo.)
Olaf
Administrator

Find all posts by this user
Quote this message in a reply
22 November 2013 14:48
Great stuff that makes it much easier now. Thanks!

Just in case, the npm-shrinkwrap file seems to be picky about the npm version: my npm install failed systematically when running npm 1.1.6 and I had to upgrade to make it work.
(This post was last modified: 2 December 2013 11:17 by Olaf.)
jakub-g
AT core team member

Find all posts by this user
Quote this message in a reply
Default  17 December 2013 16:00
One note regarding usermanual build, it's ok with node 0.8 but fails on 0.10 (probably the same compat issue as with attester, node 0.10 expect paths to be always strings while in 0.8 nulls were okay in some places).

http://jakub-g.github.io/
(This post was last modified: 17 December 2013 16:01 by jakub-g.)
simonarbuckle
AT core team member

Find all posts by this user
Quote this message in a reply
Default  13 January 2014 11:22
Hi Everyone,

There is a new update available for snippets see PR12 which allows us to work completely locally for the documentation stack, and the AT framework.

The update allows you to test your samples on a local version of the AT framework, which can be an open source version or an Amadeus version. There is also the addition of the Optimist library, which allows us to pass in arguments for the documentationPath, frameworkPath, frameworkVersion, frameworkFileName and it is also now possible to run the server without any arguments passed in, this defaults to the CDN for the framework (latest version) and GitHub for the samples. Finally, if you run the server redirecting the framework locally, you can override this for a particular session without the need to restart your server, by adding ?atversion=1.4.14 to the browser URL and reloading the page, then the framework will be requested from the CDN using the AT version you specified.

Aliases:

--dp : documentationPath
--fp : frameworkPath
--fv : frameworkVersion
--ff : frameworkFileName


Redirecting to your local framework:

Open source, local, unminified:

--fp ../at_simonarbuckle/build/target/bootstrap
--fv 1.4.13
node server.js --fp ../at_simonarbuckle/build/target/bootstrap --fv 1.4.13

Open source, local, minified:

--fp ../at_simonarbuckle/build/target/production
--fv 1.4.13
node server.js --fp ../at_simonarbuckle/build/target/production --fv 1.4.13

Amadeus, local, unminified:

--fp ../../jdevcc/aria_templates_master/at_v1.1_int/at1104_core/at/target/static/dev
--fv 1.1-SNAPSHOT
--ff aria-templates-%version%.js
node server.js --fp ../../jdevcc/aria_templates_master/at_v1.1_int/at1104_core/at/target/static/dev --fv 1.1-SNAPSHOT --ff aria-templates-%version%.js

Amadeus, local, minified:

--fp ../../jdevcc/aria_templates_master/at_v1.1_int/at1104_core/at/target/static
--fv 1.1-SNAPSHOT
--ff aria-templates-%version%.js
node server.js --fp ../../jdevcc/aria_templates_master/at_v1.1_int/at1104_core/at/target/static --fv 1.1-SNAPSHOT --ff aria-templates-%version%.js


Cheers,

Simon
Olaf
Administrator

Find all posts by this user
Quote this message in a reply
29 January 2014 09:26
I've edited Fabiano's post to reflect the fact that the default empty value of NODE_ENV means production and not development, which is safer (the code on GH has been updated.)
jakub-g
AT core team member

Find all posts by this user
Quote this message in a reply
30 January 2014 13:27
Apparently there's some interest from Bad Homburg to contribute to the usermanual (sehr gut!) hence I moved this thread to the public part of the forum.

http://jakub-g.github.io/
flongo
AT core team member

Find all posts by this user
Quote this message in a reply
Default  15 April 2014 13:32
This article explains how to get the AT user manual to run locally so that you can test your articles, snippets and samples before pushing anything to Github.

Prerequisite

You need to fork and update to the latest version those repos:

1. documentation-code
2. usermanual
3. snippets.ariatemplates.com

you need the npm-shrinkwrap.json file to copy/paste it inside usermanual folder, same level as package.json

[attachment=45]

Installation

In order to display articles, snippets and samples locally, you need to perform the following two steps:

1. Convert the .md files contained in the usermanual repository into html files and launch a server to serve them.
2. [OPTIONAL] Launch the snippet server in order to use samples and snippets contained in a local clone of the documentation-code repository. This is optional because you might want to just change the static part of the usermanual and keep using the snippets that are on the master branch of https://github.com/ariatemplates/documentation-code/

1. Static content
Inside usermanual repo (same level of package.json) copy/paste npm-shrinkwrap.json file and npm install the dependencies. In order to generate the documentation (convert .md files into html) and test it you can run
- npm run-script start if you want snippets and samples to be retrieved from https://github.com/ariatemplates/documentation-code/.
- npm run-script start-dev if you want snippets and samples to be retrieved from a local server that you will also have to launch (see the following steps).

Snippets are included in articles using <script> tags. Inside the src attribute you can see a placeholder %SNIPPETS_SERVER_URL% prefixing the snippets path. This placeholder is automatically replaced by the start or the start-dev script so that it targets the correct url.

2. [Optional] Launching a snippet server
If you are modifying snippets and samples and you want to test your local version, you need to launch a snippets server. The server fetches the code, colorizes it and sends it back.
In order to start it, from your snippets.ariatemplates.com repo perform an node server.js --dp path_to_documentation-code (e.g. node server.js --dp G:/github/fab-b_documentation-code).

There are other arguments that you can use in order to change the version of the framework that is used by the samples:

--dp : documentationPath
--fp : frameworkPath
--fv : frameworkVersion
--ff : frameworkFileName


See an earlier post in this thread for examples on how to use them.
lsimone
AT core team member

Find all posts by this user
Quote this message in a reply
Default  23 June 2014 16:58
I would like to point out that the
npm run-script start
command failes if node version 0.10 is used, while it works as described with v0.8.
Post Reply