summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorthmsdt <thomas.kulik@telekom.de>2021-10-19 12:05:48 +0200
committerthmsdt <thomas.kulik@telekom.de>2021-11-17 10:33:17 +0100
commitd6b7f66b0d3cbc4e7c92a85837a8e74906c08434 (patch)
treeaf702ffc4e707f71c72f0368e2abc40fe97ab6cf
parenteb3b0515916012651dc8f4fb8c432da13759ec56 (diff)
Add sphinx example configuration files
Issue-ID: DOC-772 Signed-off-by: thmsdt <thomas.kulik@telekom.de> Change-Id: I2cb913388cb1db28400de12d31fc74776627e9e8
-rw-r--r--examples/sphinx/.readthedocs.yaml20
-rw-r--r--examples/sphinx/README.md66
-rw-r--r--examples/sphinx/conf.py_MASTER15
-rw-r--r--examples/sphinx/conf.py_NEWBRANCH15
-rw-r--r--examples/sphinx/requirements-docs.txt1
-rw-r--r--examples/sphinx/tox.ini_MASTER25
-rw-r--r--examples/sphinx/tox.ini_NEWBRANCH25
7 files changed, 167 insertions, 0 deletions
diff --git a/examples/sphinx/.readthedocs.yaml b/examples/sphinx/.readthedocs.yaml
new file mode 100644
index 000000000..82889b5ac
--- /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
index 000000000..e8decf9a4
--- /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
index 000000000..d211470a6
--- /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
index 000000000..ea67c5518
--- /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
index 000000000..74a3b7a3f
--- /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
index 000000000..c5ed11775
--- /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
index 000000000..8b0a0fa04
--- /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