Add sphinx example configuration files

Issue-ID: DOC-772

Signed-off-by: thmsdt <thomas.kulik@telekom.de>
Change-Id: I2cb913388cb1db28400de12d31fc74776627e9e8

diff --git a/examples/sphinx/.readthedocs.yaml b/examples/sphinx/.readthedocs.yaml
new file mode 100644 (file)
index 0000000..82889b5
--- /dev/null
+++ b/examples/sphinx/.readthedocs.yaml
@@ -0,0 +1,20 @@
+---
+# .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: docs/requirements-docs.txt
+
+submodules:
+   include: all
+
+sphinx:
+  configuration: docs/conf.py

diff --git a/examples/sphinx/README.md b/examples/sphinx/README.md
new file mode 100644 (file)
index 0000000..e8decf9
--- /dev/null
+++ b/examples/sphinx/README.md
@@ -0,0 +1,66 @@
+# 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.
+Please note the different pathes, the files are located in!
+
+## FILE: tox.ini_MASTER
+
+##### USE:
+in MASTER branch of your repository
+##### PATH:
+{project}/docs
+##### TODO:
+remove _MASTER from filename
+
+## FILE: tox.ini_NEWBRANCH
+
+##### 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.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
+
+##### USE:
+in both, MASTER branch and 'NEWBRANCH' of your repository
+##### PATH:
+{project}/docs
+##### TODO:
+–
+
+## FILE: .readthedocs.yaml
+
+##### USE:
+in both, MASTER branch and 'NEWBRANCH' of your repository
+##### PATH:
+{project}
+##### TODO:
+–

diff --git a/examples/sphinx/conf.py_MASTER b/examples/sphinx/conf.py_MASTER
new file mode 100644 (file)
index 0000000..d211470
--- /dev/null
+++ b/examples/sphinx/conf.py_MASTER
@@ -0,0 +1,15 @@
+from docs_conf.conf import *
+
+branch = 'latest'
+master_doc = 'index'
+
+linkcheck_ignore = [
+    'http://localhost',
+]
+
+intersphinx_mapping = {}
+
+html_last_updated_fmt = '%d-%b-%y %H:%M'
+
+def setup(app):
+    app.add_css_file("css/ribbon.css")

diff --git a/examples/sphinx/conf.py_NEWBRANCH b/examples/sphinx/conf.py_NEWBRANCH
new file mode 100644 (file)
index 0000000..ea67c55
--- /dev/null
+++ b/examples/sphinx/conf.py_NEWBRANCH
@@ -0,0 +1,15 @@
+from docs_conf.conf import *
+
+branch = 'istanbul'
+master_doc = 'index'
+
+linkcheck_ignore = [
+    'http://localhost',
+]
+
+intersphinx_mapping = {}
+
+html_last_updated_fmt = '%d-%b-%y %H:%M'
+
+def setup(app):
+    app.add_css_file("css/ribbon.css")

diff --git a/examples/sphinx/requirements-docs.txt b/examples/sphinx/requirements-docs.txt
new file mode 100644 (file)
index 0000000..74a3b7a
--- /dev/null
+++ b/examples/sphinx/requirements-docs.txt
@@ -0,0 +1 @@
+lfdocs-conf

diff --git a/examples/sphinx/tox.ini_MASTER b/examples/sphinx/tox.ini_MASTER
new file mode 100644 (file)
index 0000000..c5ed117
--- /dev/null
+++ b/examples/sphinx/tox.ini_MASTER
@@ -0,0 +1,25 @@
+[tox]
+minversion = 1.6
+envlist = docs,
+skipsdist = true
+
+[testenv:docs]
+basepython = python3
+deps =
+    -r{toxinidir}/requirements-docs.txt
+    -chttps://git.onap.org/doc/plain/etc/upper-constraints.os.txt?h=master
+    -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h=master
+commands =
+    sphinx-build -b html -n -d {envtmpdir}/doctrees ./ {toxinidir}/_build/html
+    echo "Generated docs available in {toxinidir}/_build/html"
+whitelist_externals =
+    echo
+    git
+    sh
+
+[testenv:docs-linkcheck]
+basepython = python3
+#deps = -r{toxinidir}/requirements-docs.txt
+commands = echo "Link Checking not enforced"
+#commands = sphinx-build -b linkcheck -d {envtmpdir}/doctrees ./ {toxinidir}/_build/linkcheck
+whitelist_externals = echo
\ No newline at end of file

diff --git a/examples/sphinx/tox.ini_NEWBRANCH b/examples/sphinx/tox.ini_NEWBRANCH
new file mode 100644 (file)
index 0000000..8b0a0fa
--- /dev/null
+++ b/examples/sphinx/tox.ini_NEWBRANCH
@@ -0,0 +1,25 @@
+[tox]
+minversion = 1.6
+envlist = docs,
+skipsdist = true
+
+[testenv:docs]
+basepython = python3
+deps =
+    -r{toxinidir}/requirements-docs.txt
+    -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
+commands =
+    sphinx-build -b html -n -d {envtmpdir}/doctrees ./ {toxinidir}/_build/html
+    echo "Generated docs available in {toxinidir}/_build/html"
+whitelist_externals =
+    echo
+    git
+    sh
+
+[testenv:docs-linkcheck]
+basepython = python3
+#deps = -r{toxinidir}/requirements-docs.txt
+commands = echo "Link Checking not enforced"
+#commands = sphinx-build -b linkcheck -d {envtmpdir}/doctrees ./ {toxinidir}/_build/linkcheck
+whitelist_externals = echo
\ No newline at end of file