From ee5fbf2a3b06a3980f8f404b1dea08b24bfbe753 Mon Sep 17 00:00:00 2001 From: thmsdt Date: Tue, 19 Oct 2021 12:05:48 +0200 Subject: Add sphinx example configuration files Issue-ID: DOC-772 Signed-off-by: thmsdt Change-Id: I2cb913388cb1db28400de12d31fc74776627e9e8 (cherry picked from commit d6b7f66b0d3cbc4e7c92a85837a8e74906c08434) --- examples/sphinx/.readthedocs.yaml | 20 +++++++++++ examples/sphinx/README.md | 66 +++++++++++++++++++++++++++++++++++ examples/sphinx/conf.py_MASTER | 15 ++++++++ examples/sphinx/conf.py_NEWBRANCH | 15 ++++++++ examples/sphinx/requirements-docs.txt | 1 + examples/sphinx/tox.ini_MASTER | 25 +++++++++++++ examples/sphinx/tox.ini_NEWBRANCH | 25 +++++++++++++ 7 files changed, 167 insertions(+) create mode 100644 examples/sphinx/.readthedocs.yaml create mode 100644 examples/sphinx/README.md create mode 100644 examples/sphinx/conf.py_MASTER create mode 100644 examples/sphinx/conf.py_NEWBRANCH create mode 100644 examples/sphinx/requirements-docs.txt create mode 100644 examples/sphinx/tox.ini_MASTER create mode 100644 examples/sphinx/tox.ini_NEWBRANCH 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 -- cgit 1.2.3-korg