webdocs: allow fetching PDFs; update documentation in _tocs files

Change-Id: I9b677f0ad3b161ffb12471a989f5e8ca455baab2
Signed-off-by: Stephane Desneux <stephane.desneux@iot.bzh>

2 files changed, 69 insertions, 14 deletions

diff --git a/site/_tocs/getting_started/fetched_files.yml b/site/_tocs/getting_started/fetched_files.yml
index b2e5432..29425f6 100644
--- a/site/_tocs/getting_started/fetched_files.yml
+++ b/site/_tocs/getting_started/fetched_files.yml
@@ -1,19 +1,41 @@
-# REFERENCE ENTRY:
+##############################################################################################################
+# GLOBAL DOCUMENT
+#   <any REPOSITORY option>: global setting
+#   repositories: array of objects with documents to fetchd
+#
+# REPOSITORY ENTRY:
 # -
-#   url_fetch : gitweb fetch URL (format string with token %repo% %uri%
-#      GERRIT_FETCH=  "https://gerrit.automotivelinux.org/gerrit/gitweb?p=%repo%;a=blob_plain;f=%source%;hb=%commit%"
-#      GITHUB_FETCH= "https://raw.githubusercontent.com/%repo%/%commit%/%source%"
-#   repository: git repository name
-#      GITHUB_EDIT= "https://raw.github.com/%repo%/blob/%commit%/%source%"
-#   git_commit: git commit when not default
-#   destination_prefix: optional destination prefix 
-#   documents:
-#     -
-#       source  : "source patch within url_fetch"
-#       destination  : "optional: destination path default=path.join(destination_prefix+source)"
-#       label: "optional: friendly name for submenu default=basename(source) overloaded by file content"
-#       title: "optional: info about document (default label, overloaded by file content)"
+#   url_fetch : gitweb fetch URL (format string with token %repo% %commit% %source%, defined in configuration)
+#   url_edit  : gitweb edut URL (format string with token %repo% %commit% %source%, defined in configuration)
+#   git_name: repository name (%repo%)
+#   git_commit: git reference: revision, SHA1, branch... (%commit%)
+#   src_prefix: prefix prepended to %source%
+#   dst_prefix: prefix prepended to destination name
+#   documents: array of documents to fetch
+#
+# DOCUMENT ENTRY:
+#   source: subpath within repository (%source%)
+#   destination: local destination filename
+#   label|title: name within TOC
+#   edit|editURI: specific edition URI
 #
+# EXAMPLE:
+# ------------------------------------
+# url: "GERRIT_FETCH"
+# git_commit: "master"
+# repositories: 
+# -
+#    git_name: src/foo
+#    src_prefix: docs
+#    dst_prefix: foodocs
+#    documents:
+#       - source: intro.md
+#         label: Introduction
+#       - source: topic/README.md
+#         destination: topic.md
+#         label: My Topic
+# ------------------------------------
+##############################################################################################################
 
 url_fetch  : "GITHUB_FETCH"
 url_edit   : "GITHUB_EDIT"
diff --git a/site/_tocs/getting_started/toc_dev_en.yml b/site/_tocs/getting_started/toc_dev_en.yml
index 2681bb8..fb284a4 100644
--- a/site/_tocs/getting_started/toc_dev_en.yml
+++ b/site/_tocs/getting_started/toc_dev_en.yml
@@ -1,6 +1,39 @@
+#######################################################################
 # WARNING: 
 #  - TOC should reference .HTML and .md (Index OK but Error 404)
 #  - do not forget to run 'docbuild --tocs' after any changes 
+#
+# 
+############################ SYNTAX ###################################
+# GLOBAL OPTIONS:
+#    name: TOC (page) title
+#    template: name of template to use for this page - use 'generated_index.html' if unknown
+#    children: array of TOC entries
+#
+# TOC Entry:
+#     name: TOC entry (level 1)
+#     children:
+#         - 
+#            name: optional name for TOC entry (default: use URL FrontMatter info)
+#            url: <subdir as defined with FETCH_DIR in conf/AppDefault.js:
+#         -
+#            name: ...
+#            url: ...
+#         ...
+#
+# EXAMPLE:
+# -------------------------------
+# name: Developer Guides
+# template: generated_index.html
+# children:
+# -
+#   name: Application Framework
+#   children:
+#       - url: reference/af-main/overview.html
+#       - url: reference/af-main/afm-system-daemon.html
+#       - url: reference/af-main/afm-user-daemon.html
+# -------------------------------
+#######################################################################
 
 name: Getting started
 template: generated_index.html