Merge "update of sphinx example files"

4 files changed, 53 insertions, 21 deletions

diff --git a/examples/sphinx/.readthedocs.yaml b/examples/sphinx/.readthedocs.yaml
new file mode 100644
index 000000000..10453a93d
--- /dev/null
+++ b/examples/sphinx/.readthedocs.yaml
@@ -0,0 +1,21 @@
+---
+# .readthedocs.yml
+# # Read the Docs configuration file
+# # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+# # Required
+#
+version: 2
+
+build:
+   image: latest
+
+python:
+   version: 3.7
+   install:
+      - requirements: etc/requirements.txt
+
+submodules:
+   include: all
+
+sphinx:
+   configuration: docs/conf.py
diff --git a/examples/sphinx/README.md b/examples/sphinx/README.md
index ababb3834..9d416c889 100644
--- a/examples/sphinx/README.md
+++ b/examples/sphinx/README.md
@@ -1,40 +1,51 @@
 # Examples files
 
-Examples files for a working (basic) configuration of sphinx.
-To be used by all ONAP projects (except 'doc' project).
-Extend them to reflect the needs in your project.
+The examples files for a working (basic) configuration of sphinx should be used
+by all ONAP projects (except 'doc' project). Extend them to reflect the needs
+in your project. **Important:** The files relate on each other. Change them carefully!
 
 We provide two directories:
 - **master**: Contains configuration files used in the **development branch**.
 - **istanbul**: Contains configuration files used in the **release branch**
-   (e.g.'istanbul'). **Important**: You need to change the 'istanbul' entries
-   in the files! Replace them with the name of the new release branch.
+   (e.g.'istanbul'). **Important:** You need to change the 'istanbul' entries
+   in the files! Replace them with the name of the new release branch (e.g. 'jakarta').
 
 The additional directories named *_static* and *images* and the file
 *index.rst* are required to make the examples buildable. In the respective
-directory you can execute the '*tox -e docs*' command and the build starts. 
+directory you can execute the '*tox -e docs*' command and the build starts.
 
-## FILE: conf.py
-##### DESCRIPTION:
+---
+## conf.py
+#### DESCRIPTION:
 The “build configuration file” contains (almost) all configuration needed to
 customize Sphinx input and output behavior.
+#### SEE ALSO:
 
+https://docs.releng.linuxfoundation.org/projects/lfdocs-conf/en/latest/config.html
 
-## FILE: conf.yaml
-##### DESCRIPTION:
-todo
+https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+---
+## conf.yaml
+#### DESCRIPTION:
+Required to customize lfdocs-conf behavior.
+##### SEE ALSO:
 
-## FILE: requirements-docs.txt
-##### DESCRIPTION:
-todo
+https://docs.releng.linuxfoundation.org/projects/lfdocs-conf/en/latest/config.html
 
-
-## FILE: .readthedocs.yaml
+---
+## requirements-docs.txt
 ##### DESCRIPTION:
-todo
+Contains the required libraries to be used by Sphinx.
 
+---
+## .readthedocs.yaml
+##### DESCRIPTION:
+Required to customize the ReadTheDocs input and output behavior. **Important:** This file is located in your {project} root directory (e.g. *doc/.readthedocs.yaml*).
 
-## FILE: tox.ini
+---
+## tox.ini
 ##### DESCRIPTION:
-todo
\ No newline at end of file
+Required to customize different tox environments.
+##### SEE ALSO:
+https://tox.wiki/en/latest/config.html
\ No newline at end of file
diff --git a/examples/sphinx/istanbul/conf.yaml b/examples/sphinx/istanbul/conf.yaml
index 44de212d1..d2e9275a9 100644
--- a/examples/sphinx/istanbul/conf.yaml
+++ b/examples/sphinx/istanbul/conf.yaml
@@ -2,6 +2,6 @@
 project_cfg: onap
 project: onap
 
-# Change this to ReleaseBranchName to modify the header
+# Change this to {releasename} to modify the header
 default-version: istanbul
 #
diff --git a/examples/sphinx/master/conf.yaml b/examples/sphinx/master/conf.yaml
index ab5928131..747e500ce 100644
--- a/examples/sphinx/master/conf.yaml
+++ b/examples/sphinx/master/conf.yaml
@@ -2,6 +2,6 @@
 project_cfg: onap
 project: onap
 
-# Change this to ReleaseBranchName to modify the header
+# Change this to {releasename} to modify the header
 default-version: latest
 #