update README: how to initialise doc environment

Signed-off-by: Clément Bénier <clement.benier@iot.bzh>

1 files changed, 56 insertions, 18 deletions

diff --git a/README.md b/README.md
index b7c0a7d..97cb948 100644
--- a/README.md
+++ b/README.md
@@ -1,37 +1,52 @@
-Introduction
-============
+# Introduction
 
 This repository contains AGL documentation website template, rendering is visible at http://docs.automotivelinux.org
 This website relies on the generator located in [docs-tools](https://github.com/automotive-grade-linux/docs-tools)
 
 TODO: old documentation below. Should be rewritten to match new git repo scheme.
 
-Installing
-==========
+# Installing
 
-## dependencies: webdoc
+Get the setupdocs script to initialise your environment.
 
-See how to install webdocs: read file in doctools/webdocs/README.md
+```bash
+wget https://raw.githubusercontent.com/automotive-grade-linux/docs-webtemplate/master/setupdocs.sh
+```
+
+This script fetches [docs-tools](https://github.com/automotive-grade-linux/docs-tools), install npm modules.
+
+```bash
+mkdir docs-webtemplate
+bash setupdocs.sh --directory=docs-webtemplate
+```
+
+For consulting help, do:
 
-## configure webdoc
+```bash
+bash setupdocs.sh --help
+```
+
+## Configure webdoc
 
 Some default configuration options can be overridden in the project directory. For this, you can adjust the configuration file conf/AppDefaults.js
 
 Other configuration files in conf/ starting by an underscore (_) are used by Jekyll. Some options may also be adjusted in particular in conf/_config.yml.
 
 ## generate a 1st site from your template
-```
- ../doctools/webdocs/docbuild --clean  # deleted all generated file if any
- ../doctools/webdocs/docbuild --fetch [--force]  # collect doc from github (fetch list in content/toc/*/fetch_files.yml)
- ../doctools/webdocs/docbuild --build --serve --watch --incremental # build config/tocs, generate html and start a local webserver
+
+```bash
+ ./doctools/webdocs/docbuild --clean  # deleted all generated file if any
+ ./doctools/webdocs/docbuild --fetch [--force]  # collect doc from github (fetch list in content/toc/*/fetch_files.yml)
+ ./doctools/webdocs/docbuild --build --serve --watch --incremental # build config/tocs, generate html and start a local webserver
 
  xdg-open http://localhost:4000
 
- ../doctools/webdocs/docbuild --push --verbose # push generated to production webserver (check conf/AppDefault 1st)
+ ./doctools/webdocs/docbuild --push --verbose # push generated to production webserver (check conf/AppDefault 1st)
 ```
 
 Alternatively, a Makefile can be used and defines the most common operations:
-```
+
+```bash
  make fetch
  make localFetch
  make build
@@ -40,22 +55,45 @@ Alternatively, a Makefile can be used and defines the most common operations:
  make clean
 ```
 
-## start writing documentation
+## Work with local repos
+
+For local fetch, a specific file named  "__fetched_files_local.yml" was introduced.
+
+This file is used to overload url_fetch in fetched_files.yml in order to use local repositories on not remote ones.
+
+Thus, this file is needed to be added in the docs-webtemplate root, see an example below:
+
+```bash
+############__fetched_files_local.yml##############
+-
+    url_fetch : <pathToDocsSources>/docs-sources/
+    git_name   : "automotive-grade-linux/docs-sources"
+-
+    url_fetch : <pathToXdsDocs>/xds-docs/
+    git_name   : src/xds/xds-docs
+
+###################################################
+```
+
+## Start writing documentation
 
 - the directory ./site holds your website content
 - site/* directories not prefixed with "_" represent en entry within the menu
 - site/_* directories contain template, configuration, options used by Jekyll
 - site/_data is a special directory that hold both static and generated files to adjust page/site values within html pages
 - content/toc/*/toc_VERSION_LANGUAGE.yml TOC(TableOfContent) and Fetch definitions
-- site/_layouts and site/_includes holds page template 
+- site/_layouts and site/_includes holds page template
 - site/static holds assets (static images, CSS etc.)
 
 - register at https://community.algolia.com/docsearch/ and update your apikey into conf/_config.yml
 
+## Notes
+
+- The setupdocs.sh script can be used to update the docs-tools repository.
+- The setupdocs.sh script cannot update the current repository, use git commands instead.
 
 ## bugs
 
-```
+```bash
  --watch to automatically regenerate pages on markdown file, you should force "./build --configs" when changing TOC or versions.
-```
-
+```
\ No newline at end of file