From acd34d7c138f1764ccc90088d9e1f0b51aa0ed60 Mon Sep 17 00:00:00 2001 From: thmsdt Date: Mon, 18 Jul 2022 14:51:16 +0200 Subject: update sphinx example configuraton Issue-ID: DOC-798 Signed-off-by: thmsdt Change-Id: Ie3032dbaf531e2de1ee144a946a3e4f51fc04f9a --- examples/sphinx/README.md | 18 +++---- examples/sphinx/istanbul/conf.py | 41 +++++++++++---- examples/sphinx/istanbul/conf.yaml | 7 --- examples/sphinx/istanbul/requirements-docs.txt | 4 +- examples/sphinx/istanbul/tox.ini | 70 ++++++++++++++++++++++---- examples/sphinx/master/conf.py | 41 +++++++++++---- examples/sphinx/master/conf.yaml | 7 --- examples/sphinx/master/requirements-docs.txt | 4 +- examples/sphinx/master/tox.ini | 70 ++++++++++++++++++++++---- 9 files changed, 199 insertions(+), 63 deletions(-) delete mode 100644 examples/sphinx/istanbul/conf.yaml delete mode 100644 examples/sphinx/master/conf.yaml diff --git a/examples/sphinx/README.md b/examples/sphinx/README.md index 616961e50..ec94cd0b1 100644 --- a/examples/sphinx/README.md +++ b/examples/sphinx/README.md @@ -27,16 +27,6 @@ https://docs.releng.linuxfoundation.org/projects/lfdocs-conf/en/latest/config.ht https://www.sphinx-doc.org/en/master/usage/configuration.html ---- -## conf.yaml -#### DESCRIPTION: -Required to customize lfdocs-conf behavior. -#### PATH: -{project}/docs/conf.yaml -##### SEE ALSO: - -https://docs.releng.linuxfoundation.org/projects/lfdocs-conf/en/latest/config.html - --- ## requirements-docs.txt ##### DESCRIPTION: @@ -49,6 +39,7 @@ Contains the required libraries to be used by Sphinx. Required to customize the ReadTheDocs input and output behavior. **Important:** This file is located in your {project} root directory (e.g. *doc/.readthedocs.yaml*). #### PATH: {project}/.readthedocs.yaml + --- ## tox.ini ##### DESCRIPTION: @@ -56,4 +47,9 @@ Required to customize different tox environments. #### PATH: {project}/tox.ini ##### SEE ALSO: -https://tox.wiki/en/latest/config.html \ No newline at end of file +https://tox.wiki/en/latest/config.html + +--- +## index.rst +##### DESCRIPTION: +The reStructuredText Cheat Sheet as an example .rst file diff --git a/examples/sphinx/istanbul/conf.py b/examples/sphinx/istanbul/conf.py index 1d6c7d357..966fe7dfe 100644 --- a/examples/sphinx/istanbul/conf.py +++ b/examples/sphinx/istanbul/conf.py @@ -1,17 +1,40 @@ -from docs_conf.conf import * +project = "onap" +release = "istanbul" +version = "istanbul" -branch = 'istanbul' -master_doc = 'index' +author: "Open Network Automation Platform" +# yamllint disable-line rule:line-length +copyright: "ONAP. Licensed under Creative Commons Attribution 4.0 International License." -linkcheck_ignore = [ - 'http://localhost', -] +pygments_style = "sphinx" +html_theme = "sphinx_rtd_theme" +html_theme_options = { + "style_nav_header_background": "white", + "sticky_navigation": "False" } +html_logo = "_static/logo_onap_2017.png" +html_favicon = "_static/favicon.ico" +html_static_path = ["_static"] +html_show_sphinx = False -exclude_patterns = [ - '.tox' -] +extensions = [ + 'sphinx.ext.intersphinx','sphinxcontrib.blockdiag', + 'sphinxcontrib.seqdiag', 'sphinxcontrib.swaggerdoc', 'sphinx.ext.graphviz'] + +# +# Map to 'latest' if this file is used in 'latest' (master) 'doc' branch. +# Change to {releasename} after you have created the new 'doc' branch. +# + +branch = 'istanbul' intersphinx_mapping = {} +doc_url = 'https://docs.onap.org/projects' +master_doc = 'index' + +# +# Example: +# intersphinx_mapping['onap-aai-aai-common'] = ('{}/onap-aai-aai-common/en/%s'.format(doc_url) % branch, None) +# html_last_updated_fmt = '%d-%b-%y %H:%M' diff --git a/examples/sphinx/istanbul/conf.yaml b/examples/sphinx/istanbul/conf.yaml deleted file mode 100644 index d2e9275a9..000000000 --- a/examples/sphinx/istanbul/conf.yaml +++ /dev/null @@ -1,7 +0,0 @@ ---- -project_cfg: onap -project: onap - -# Change this to {releasename} to modify the header -default-version: istanbul -# diff --git a/examples/sphinx/istanbul/requirements-docs.txt b/examples/sphinx/istanbul/requirements-docs.txt index cc2d12c20..dc55d67b4 100644 --- a/examples/sphinx/istanbul/requirements-docs.txt +++ b/examples/sphinx/istanbul/requirements-docs.txt @@ -1,6 +1,8 @@ -lfdocs-conf sphinx>=4.2.0 # BSD sphinx-rtd-theme>=1.0.0 # MIT +sphinxcontrib-blockdiag # BSD +sphinxcontrib-seqdiag # BSD +sphinxcontrib-swaggerdoc autopep8 sphinxcontrib-spelling pylint diff --git a/examples/sphinx/istanbul/tox.ini b/examples/sphinx/istanbul/tox.ini index 8b5bc99bf..6505b8512 100644 --- a/examples/sphinx/istanbul/tox.ini +++ b/examples/sphinx/istanbul/tox.ini @@ -6,20 +6,72 @@ 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 + -r{toxinidir}/etc/requirements-docs.txt + -c{toxinidir}/etc/upper-constraints.os.txt + -c{toxinidir}/etc/upper-constraints.onap.txt commands = - sphinx-build -W -b html -n -d {envtmpdir}/doctrees ./ {toxinidir}/_build/html - echo "Generated docs available in {toxinidir}/_build/html" + sphinx-build -W -q -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html + echo "Generated docs available in {toxinidir}/docs/_build/html" whitelist_externals = echo + git + sh + +[testenv:docs-templates] +basepython = python3 +deps = + -r{toxinidir}/etc/requirements-docs.txt + -c{toxinidir}/etc/upper-constraints.os.txt + -c{toxinidir}/etc/upper-constraints.onap.txt +commands = + sphinx-build -b html -n -d {envtmpdir}/doctrees -c {toxinidir}/docs ./docs/guides/onap-developer/how-to-use-docs/templates {toxinidir}/docs/_build/html/templates + echo "Generated docs available in {toxinidir}/docs/_build/html/templates" +whitelist_externals = + echo + +[testenv:local] +basepython = python3 +deps = + -r{toxinidir}/etc/requirements-docs.txt + -c{toxinidir}/etc/upper-constraints.os.txt + -c{toxinidir}/etc/upper-constraints.onap.txt +commands = + git submodule update --depth 100 --init + sphinx-build -q -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html + echo "Generated docs available in {toxinidir}/docs/_build/html" +whitelist_externals = + echo + git [testenv:docs-linkcheck] 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 + -r{toxinidir}/etc/requirements-docs.txt + -c{toxinidir}/etc/upper-constraints.os.txt + -c{toxinidir}/etc/upper-constraints.onap.txt +commands = sphinx-build -W -q -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck + +[testenv:spellcheck] +basepython = python3 +deps = + -r{toxinidir}/etc/requirements-docs.txt + -c{toxinidir}/etc/upper-constraints.os.txt + -c{toxinidir}/etc/upper-constraints.onap.txt +commands = + sphinx-build -b spelling -Dextensions=sphinxcontrib.spelling -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/spellcheck + +[testenv:autopep8] +deps = + -r{toxinidir}/etc/requirements-docs.txt + -c{toxinidir}/etc/upper-constraints.os.txt + -c{toxinidir}/etc/upper-constraints.onap.txt +commands = + autopep8 --max-line-length 120 --in-place docs/conf.py + +[testenv:pylint] +deps = + -r{toxinidir}/etc/requirements-docs.txt + -c{toxinidir}/etc/upper-constraints.os.txt + -c{toxinidir}/etc/upper-constraints.onap.txt commands = - sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees ./ {toxinidir}/_build/linkcheck + pylint --max-line-length=120 --disable=missing-docstring --reports=y --score=y --output-format=colorized docs/conf.py diff --git a/examples/sphinx/master/conf.py b/examples/sphinx/master/conf.py index e782429a1..12825ee2d 100644 --- a/examples/sphinx/master/conf.py +++ b/examples/sphinx/master/conf.py @@ -1,17 +1,40 @@ -from docs_conf.conf import * +project = "onap" +release = "master" +version = "master" -branch = 'latest' -master_doc = 'index' +author: "Open Network Automation Platform" +# yamllint disable-line rule:line-length +copyright: "ONAP. Licensed under Creative Commons Attribution 4.0 International License." -linkcheck_ignore = [ - 'http://localhost', -] +pygments_style = "sphinx" +html_theme = "sphinx_rtd_theme" +html_theme_options = { + "style_nav_header_background": "white", + "sticky_navigation": "False" } +html_logo = "_static/logo_onap_2017.png" +html_favicon = "_static/favicon.ico" +html_static_path = ["_static"] +html_show_sphinx = False -exclude_patterns = [ - '.tox' -] +extensions = [ + 'sphinx.ext.intersphinx','sphinxcontrib.blockdiag', + 'sphinxcontrib.seqdiag', 'sphinxcontrib.swaggerdoc', 'sphinx.ext.graphviz'] + +# +# Map to 'latest' if this file is used in 'latest' (master) 'doc' branch. +# Change to {releasename} after you have created the new 'doc' branch. +# + +branch = 'latest' intersphinx_mapping = {} +doc_url = 'https://docs.onap.org/projects' +master_doc = 'index' + +# +# Example: +# intersphinx_mapping['onap-aai-aai-common'] = ('{}/onap-aai-aai-common/en/%s'.format(doc_url) % branch, None) +# html_last_updated_fmt = '%d-%b-%y %H:%M' diff --git a/examples/sphinx/master/conf.yaml b/examples/sphinx/master/conf.yaml deleted file mode 100644 index 747e500ce..000000000 --- a/examples/sphinx/master/conf.yaml +++ /dev/null @@ -1,7 +0,0 @@ ---- -project_cfg: onap -project: onap - -# Change this to {releasename} to modify the header -default-version: latest -# diff --git a/examples/sphinx/master/requirements-docs.txt b/examples/sphinx/master/requirements-docs.txt index cc2d12c20..dc55d67b4 100644 --- a/examples/sphinx/master/requirements-docs.txt +++ b/examples/sphinx/master/requirements-docs.txt @@ -1,6 +1,8 @@ -lfdocs-conf sphinx>=4.2.0 # BSD sphinx-rtd-theme>=1.0.0 # MIT +sphinxcontrib-blockdiag # BSD +sphinxcontrib-seqdiag # BSD +sphinxcontrib-swaggerdoc autopep8 sphinxcontrib-spelling pylint diff --git a/examples/sphinx/master/tox.ini b/examples/sphinx/master/tox.ini index 9057fb77f..6505b8512 100644 --- a/examples/sphinx/master/tox.ini +++ b/examples/sphinx/master/tox.ini @@ -6,20 +6,72 @@ 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 + -r{toxinidir}/etc/requirements-docs.txt + -c{toxinidir}/etc/upper-constraints.os.txt + -c{toxinidir}/etc/upper-constraints.onap.txt commands = - sphinx-build -W -b html -n -d {envtmpdir}/doctrees ./ {toxinidir}/_build/html - echo "Generated docs available in {toxinidir}/_build/html" + sphinx-build -W -q -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html + echo "Generated docs available in {toxinidir}/docs/_build/html" whitelist_externals = echo + git + sh + +[testenv:docs-templates] +basepython = python3 +deps = + -r{toxinidir}/etc/requirements-docs.txt + -c{toxinidir}/etc/upper-constraints.os.txt + -c{toxinidir}/etc/upper-constraints.onap.txt +commands = + sphinx-build -b html -n -d {envtmpdir}/doctrees -c {toxinidir}/docs ./docs/guides/onap-developer/how-to-use-docs/templates {toxinidir}/docs/_build/html/templates + echo "Generated docs available in {toxinidir}/docs/_build/html/templates" +whitelist_externals = + echo + +[testenv:local] +basepython = python3 +deps = + -r{toxinidir}/etc/requirements-docs.txt + -c{toxinidir}/etc/upper-constraints.os.txt + -c{toxinidir}/etc/upper-constraints.onap.txt +commands = + git submodule update --depth 100 --init + sphinx-build -q -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html + echo "Generated docs available in {toxinidir}/docs/_build/html" +whitelist_externals = + echo + git [testenv:docs-linkcheck] 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 + -r{toxinidir}/etc/requirements-docs.txt + -c{toxinidir}/etc/upper-constraints.os.txt + -c{toxinidir}/etc/upper-constraints.onap.txt +commands = sphinx-build -W -q -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck + +[testenv:spellcheck] +basepython = python3 +deps = + -r{toxinidir}/etc/requirements-docs.txt + -c{toxinidir}/etc/upper-constraints.os.txt + -c{toxinidir}/etc/upper-constraints.onap.txt +commands = + sphinx-build -b spelling -Dextensions=sphinxcontrib.spelling -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/spellcheck + +[testenv:autopep8] +deps = + -r{toxinidir}/etc/requirements-docs.txt + -c{toxinidir}/etc/upper-constraints.os.txt + -c{toxinidir}/etc/upper-constraints.onap.txt +commands = + autopep8 --max-line-length 120 --in-place docs/conf.py + +[testenv:pylint] +deps = + -r{toxinidir}/etc/requirements-docs.txt + -c{toxinidir}/etc/upper-constraints.os.txt + -c{toxinidir}/etc/upper-constraints.onap.txt commands = - sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees ./ {toxinidir}/_build/linkcheck + pylint --max-line-length=120 --disable=missing-docstring --reports=y --score=y --output-format=colorized docs/conf.py -- cgit 1.2.3-korg