From 3093269296e267427debd31e180ac29fcab349df Mon Sep 17 00:00:00 2001
From: Cédric Ollivier <cedric.ollivier@orange.com>
Date: Mon, 22 Nov 2021 14:21:29 +0100
Subject: Make examples buildable
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

It now excludes .tox from conf.py.
It locally clones docutils cheatsheet as examples (it should be noted
that cheatsheet.txt is renamed index.rst in it).

[1] https://docutils.sourceforge.io/docs/user/rst/cheatsheet.txt

Issue-ID: DOC-772

Signed-off-by: Cédric Ollivier <cedric.ollivier@orange.com>
Change-Id: Ifd616b797d5a48da5df77b0dfaa0613497b742d8
---
 examples/sphinx/README.md | 72 +++++++++++++++--------------------------------
 1 file changed, 23 insertions(+), 49 deletions(-)

(limited to 'examples/sphinx/README.md')

diff --git a/examples/sphinx/README.md b/examples/sphinx/README.md
index e8decf9a4..ababb3834 100644
--- a/examples/sphinx/README.md
+++ b/examples/sphinx/README.md
@@ -3,64 +3,38 @@
 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.
-Please note the different pathes, the files are located in!
 
-## FILE: tox.ini_MASTER
+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.
 
-##### USE:
-in MASTER branch of your repository
-##### PATH:
-{project}/docs
-##### TODO:
-remove _MASTER from filename
+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. 
 
-## FILE: tox.ini_NEWBRANCH
+## FILE: conf.py
+##### DESCRIPTION:
+The “build configuration file” contains (almost) all configuration needed to
+customize Sphinx input and output behavior.
 
-##### USE:
-in 'NEWBRANCH' of your repository
-##### PATH:
-{project}/docs
-##### TODO:
-remove _NEWBRANCH from filename
 
-update release name in the following lines:
-```
--chttps://git.onap.org/doc/plain/etc/upper-constraints.os.txt?h=istanbul
--chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h=istanbul
-```
+## FILE: conf.yaml
+##### DESCRIPTION:
+todo
 
-## FILE: conf.py_MASTER
-
-##### USE:
-in MASTER branch of your repository
-##### PATH:
-{project}/docs
-##### TODO:
-remove _MASTER from filename
-
-## FILE: conf.py_NEWBRANCH
-
-##### USE:
-in 'NEWBRANCH' of your repository
-##### PATH:
-{project}/docs
-##### TODO:
-remove _NEWBRANCH from filename
 
 ## FILE: requirements-docs.txt
+##### DESCRIPTION:
+todo
 
-##### USE:
-in both, MASTER branch and 'NEWBRANCH' of your repository
-##### PATH:
-{project}/docs
-##### TODO:
-–
 
 ## FILE: .readthedocs.yaml
+##### DESCRIPTION:
+todo
+
 
-##### USE:
-in both, MASTER branch and 'NEWBRANCH' of your repository
-##### PATH:
-{project}
-##### TODO:
-–
+## FILE: tox.ini
+##### DESCRIPTION:
+todo
\ No newline at end of file
-- 
cgit 1.2.3-korg