From 7e0db8a223e9d7a693c7120a5beb91df40fef82f Mon Sep 17 00:00:00 2001 From: thmsdt Date: Tue, 16 Aug 2022 13:10:56 +0200 Subject: update sphinx example config files Issue-ID: DOC-798 Signed-off-by: thmsdt Change-Id: I74a213993ada2b3697b58270c30c61326b151f7b --- examples/sphinx/README.md | 6 +- examples/sphinx/istanbul/_static/css/ribbon.css | 63 ---------- examples/sphinx/istanbul/_static/favicon.ico | Bin 2102 -> 0 bytes .../sphinx/istanbul/_static/logo_onap_2017.png | Bin 12278 -> 0 bytes examples/sphinx/istanbul/conf.py | 42 ------- examples/sphinx/istanbul/images/biohazard.png | Bin 179 -> 0 bytes examples/sphinx/istanbul/index.rst | 132 --------------------- examples/sphinx/istanbul/requirements-docs.txt | 8 -- examples/sphinx/istanbul/tox.ini | 77 ------------ examples/sphinx/release/_static/css/ribbon.css | 63 ++++++++++ examples/sphinx/release/_static/favicon.ico | Bin 0 -> 2102 bytes examples/sphinx/release/_static/logo_onap_2017.png | Bin 0 -> 12278 bytes examples/sphinx/release/conf.py | 42 +++++++ examples/sphinx/release/images/biohazard.png | Bin 0 -> 179 bytes examples/sphinx/release/index.rst | 132 +++++++++++++++++++++ examples/sphinx/release/requirements-docs.txt | 8 ++ examples/sphinx/release/tox.ini | 77 ++++++++++++ 17 files changed, 325 insertions(+), 325 deletions(-) delete mode 100644 examples/sphinx/istanbul/_static/css/ribbon.css delete mode 100755 examples/sphinx/istanbul/_static/favicon.ico delete mode 100644 examples/sphinx/istanbul/_static/logo_onap_2017.png delete mode 100644 examples/sphinx/istanbul/conf.py delete mode 100644 examples/sphinx/istanbul/images/biohazard.png delete mode 100644 examples/sphinx/istanbul/index.rst delete mode 100644 examples/sphinx/istanbul/requirements-docs.txt delete mode 100644 examples/sphinx/istanbul/tox.ini create mode 100644 examples/sphinx/release/_static/css/ribbon.css create mode 100755 examples/sphinx/release/_static/favicon.ico create mode 100644 examples/sphinx/release/_static/logo_onap_2017.png create mode 100644 examples/sphinx/release/conf.py create mode 100644 examples/sphinx/release/images/biohazard.png create mode 100644 examples/sphinx/release/index.rst create mode 100644 examples/sphinx/release/requirements-docs.txt create mode 100644 examples/sphinx/release/tox.ini diff --git a/examples/sphinx/README.md b/examples/sphinx/README.md index ec94cd0b1..8c1e339e4 100644 --- a/examples/sphinx/README.md +++ b/examples/sphinx/README.md @@ -6,9 +6,9 @@ in your project. **Important:** The files relate on each other. Change them care 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 (e.g. 'jakarta'). +- **release**: Contains configuration files used in the **release branch** + (e.g.'kohn'). **Important:** You need to change the 'kohn' entries + in the files! Replace them with the name of the new release branch. The additional directories named *_static* and *images* and the file *index.rst* are required to make the examples buildable. In the respective diff --git a/examples/sphinx/istanbul/_static/css/ribbon.css b/examples/sphinx/istanbul/_static/css/ribbon.css deleted file mode 100644 index 6008cb1a0..000000000 --- a/examples/sphinx/istanbul/_static/css/ribbon.css +++ /dev/null @@ -1,63 +0,0 @@ -.ribbon { - z-index: 1000; - background-color: #a00; - overflow: hidden; - white-space: nowrap; - position: fixed; - top: 25px; - right: -50px; - -webkit-transform: rotate(45deg); - -moz-transform: rotate(45deg); - -ms-transform: rotate(45deg); - -o-transform: rotate(45deg); - transform: rotate(45deg); - -webkit-box-shadow: 0 0 10px #888; - -moz-box-shadow: 0 0 10px #888; - box-shadow: 0 0 10px #888; - -} - -.ribbon a { - border: 1px solid #faa; - color: #fff; - display: block; - font: bold 81.25% 'Helvetica Neue', Helvetica, Arial, sans-serif; - margin: 1px 0; - padding: 10px 50px; - text-align: center; - text-decoration: none; - text-shadow: 0 0 5px #444; - transition: 0.5s; -} - -.ribbon a:hover { - background: #c11; - color: #fff; -} - - -/* override table width restrictions */ -@media screen and (min-width: 767px) { - - .wy-table-responsive table td, .wy-table-responsive table th { - /* !important prevents the common CSS stylesheets from overriding - this as on RTD they are loaded after this stylesheet */ - white-space: normal !important; - } - - .wy-table-responsive { - overflow: visible !important; - } -} - -@media screen and (max-width: 767px) { - .wy-table-responsive table td { - white-space: nowrap; - } -} - -/* fix width of the screen */ - -.wy-nav-content { - max-width: none; -} diff --git a/examples/sphinx/istanbul/_static/favicon.ico b/examples/sphinx/istanbul/_static/favicon.ico deleted file mode 100755 index cb712ebd2..000000000 Binary files a/examples/sphinx/istanbul/_static/favicon.ico and /dev/null differ diff --git a/examples/sphinx/istanbul/_static/logo_onap_2017.png b/examples/sphinx/istanbul/_static/logo_onap_2017.png deleted file mode 100644 index 5d064f431..000000000 Binary files a/examples/sphinx/istanbul/_static/logo_onap_2017.png and /dev/null differ diff --git a/examples/sphinx/istanbul/conf.py b/examples/sphinx/istanbul/conf.py deleted file mode 100644 index 67944beb6..000000000 --- a/examples/sphinx/istanbul/conf.py +++ /dev/null @@ -1,42 +0,0 @@ -project = "onap" -release = "istanbul" -version = "istanbul" - -author = "Open Network Automation Platform" -# yamllint disable-line rule:line-length -copyright = "ONAP. Licensed under Creative Commons Attribution 4.0 International License" - -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 - -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' - -def setup(app): - app.add_css_file("css/ribbon.css") diff --git a/examples/sphinx/istanbul/images/biohazard.png b/examples/sphinx/istanbul/images/biohazard.png deleted file mode 100644 index ae4629d8b..000000000 Binary files a/examples/sphinx/istanbul/images/biohazard.png and /dev/null differ diff --git a/examples/sphinx/istanbul/index.rst b/examples/sphinx/istanbul/index.rst deleted file mode 100644 index c7685a558..000000000 --- a/examples/sphinx/istanbul/index.rst +++ /dev/null @@ -1,132 +0,0 @@ -===================================================== - The reStructuredText_ Cheat Sheet: Syntax Reminders -===================================================== -:Info: See for introductory docs. -:Author: David Goodger -:Date: $Date: 2021-03-05 22:14:40 +0100 (Fr, 05. Mär 2021) $ -:Revision: $Revision: 8631 $ -:Description: This is a "docinfo block", or bibliographic field list - -.. NOTE:: If you are reading this as HTML, please read - ``_ instead to see the input syntax examples! - -Section Structure -================= -Section titles are underlined or overlined & underlined. - -Body Elements -============= -Grid table: - -+--------------------------------+-----------------------------------+ -| Paragraphs are flush-left, | Literal block, preceded by "::":: | -| separated by blank lines. | | -| | Indented | -| Block quotes are indented. | | -+--------------------------------+ or:: | -| >>> print 'Doctest block' | | -| Doctest block | > Quoted | -+--------------------------------+-----------------------------------+ -| | Line blocks preserve line breaks & indents. [new in 0.3.6] | -| | Useful for addresses, verse, and adornment-free lists; long | -| lines can be wrapped with continuation lines. | -+--------------------------------------------------------------------+ - -Simple tables: - -================ ============================================================ -List Type Examples (syntax in the `text source `_) -================ ============================================================ -Bullet list * items begin with "-", "+", or "*" -Enumerated list 1. items use any variation of "1.", "A)", and "(i)" - #. also auto-enumerated -Definition list Term is flush-left : optional classifier - Definition is indented, no blank line between -Field list :field name: field body -Option list -o at least 2 spaces between option & description -================ ============================================================ - -================ ============================================================ -Explicit Markup Examples (visible in the `text source`_) -================ ============================================================ -Footnote .. [1] Manually numbered or [#] auto-numbered - (even [#labelled]) or [*] auto-symbol -Citation .. [CIT2002] A citation. -Hyperlink Target .. _reStructuredText: http://docutils.sf.net/rst.html - .. _indirect target: reStructuredText_ - .. _internal target: -Anonymous Target __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html -Directive ("::") .. image:: images/biohazard.png -Substitution Def .. |substitution| replace:: like an inline directive -Comment .. is anything else -Empty Comment (".." on a line by itself, with blank lines before & after, - used to separate indentation contexts) -================ ============================================================ - -Inline Markup -============= -*emphasis*; **strong emphasis**; `interpreted text`; `interpreted text -with role`:emphasis:; ``inline literal text``; standalone hyperlink, -http://docutils.sourceforge.net; named reference, reStructuredText_; -`anonymous reference`__; footnote reference, [1]_; citation reference, -[CIT2002]_; |substitution|; _`inline internal target`. - -Directive Quick Reference -========================= -See for full info. - -================ ============================================================ -Directive Name Description (Docutils version added to, in [brackets]) -================ ============================================================ -attention Specific admonition; also "caution", "danger", - "error", "hint", "important", "note", "tip", "warning" -admonition Generic titled admonition: ``.. admonition:: By The Way`` -image ``.. image:: picture.png``; many options possible -figure Like "image", but with optional caption and legend -topic ``.. topic:: Title``; like a mini section -sidebar ``.. sidebar:: Title``; like a mini parallel document -parsed-literal A literal block with parsed inline markup -rubric ``.. rubric:: Informal Heading`` -epigraph Block quote with class="epigraph" -highlights Block quote with class="highlights" -pull-quote Block quote with class="pull-quote" -compound Compound paragraphs [0.3.6] -container Generic block-level container element [0.3.10] -table Create a titled table [0.3.1] -list-table Create a table from a uniform two-level bullet list [0.3.8] -csv-table Create a table from CSV data [0.3.4] -contents Generate a table of contents -sectnum Automatically number sections, subsections, etc. -header, footer Create document decorations [0.3.8] -target-notes Create an explicit footnote for each external target -math Mathematical notation (input in LaTeX format) -meta Document metadata -include Read an external reST file as if it were inline -raw Non-reST data passed untouched to the Writer -replace Replacement text for substitution definitions -unicode Unicode character code conversion for substitution defs -date Generates today's date; for substitution defs -class Set a "class" attribute on the next element -role Create a custom interpreted text role [0.3.2] -default-role Set the default interpreted text role [0.3.10] -title Set the metadata document title [0.3.10] -================ ============================================================ - -Interpreted Text Role Quick Reference -===================================== -See for full info. - -================ ============================================================ -Role Name Description -================ ============================================================ -emphasis Equivalent to *emphasis* -literal Equivalent to ``literal`` but processes backslash escapes -math Mathematical notation (input in LaTeX format) -PEP Reference to a numbered Python Enhancement Proposal -RFC Reference to a numbered Internet Request For Comments -raw For non-reST data; cannot be used directly (see docs) [0.3.6] -strong Equivalent to **strong** -sub Subscript -sup Superscript -title Title reference (book, etc.); standard default role -================ ============================================================ diff --git a/examples/sphinx/istanbul/requirements-docs.txt b/examples/sphinx/istanbul/requirements-docs.txt deleted file mode 100644 index dc55d67b4..000000000 --- a/examples/sphinx/istanbul/requirements-docs.txt +++ /dev/null @@ -1,8 +0,0 @@ -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 deleted file mode 100644 index 6505b8512..000000000 --- a/examples/sphinx/istanbul/tox.ini +++ /dev/null @@ -1,77 +0,0 @@ -[tox] -minversion = 1.6 -envlist = docs,docs-linkcheck -skipsdist = true - -[testenv:docs] -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 -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}/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 = - pylint --max-line-length=120 --disable=missing-docstring --reports=y --score=y --output-format=colorized docs/conf.py diff --git a/examples/sphinx/release/_static/css/ribbon.css b/examples/sphinx/release/_static/css/ribbon.css new file mode 100644 index 000000000..d03a26b20 --- /dev/null +++ b/examples/sphinx/release/_static/css/ribbon.css @@ -0,0 +1,63 @@ +.ribbon { + z-index: 1000; + background-color: #a00; + overflow: hidden; + white-space: nowrap; + position: fixed; + top: 25px; + right: -50px; + -webkit-transform: rotate(45deg); + -moz-transform: rotate(45deg); + -ms-transform: rotate(45deg); + -o-transform: rotate(45deg); + transform: rotate(45deg); + -webkit-box-shadow: 0 0 10px #888; + -moz-box-shadow: 0 0 10px #888; + box-shadow: 0 0 10px #888; + + } + + .ribbon a { + border: 1px solid #faa; + color: #fff; + display: block; + font: bold 81.25% 'Helvetica Neue', Helvetica, Arial, sans-serif; + margin: 1px 0; + padding: 10px 50px; + text-align: center; + text-decoration: none; + text-shadow: 0 0 5px #444; + transition: 0.5s; + } + + .ribbon a:hover { + background: #c11; + color: #fff; + } + + + /* override table width restrictions */ + @media screen and (min-width: 767px) { + + .wy-table-responsive table td, .wy-table-responsive table th { + /* !important prevents the common CSS stylesheets from overriding + this as on RTD they are loaded after this stylesheet */ + white-space: normal !important; + } + + .wy-table-responsive { + overflow: visible !important; + } + } + + @media screen and (max-width: 767px) { + .wy-table-responsive table td { + white-space: nowrap; + } + } + + /* fix width of the screen */ + + .wy-nav-content { + max-width: 800px; + } \ No newline at end of file diff --git a/examples/sphinx/release/_static/favicon.ico b/examples/sphinx/release/_static/favicon.ico new file mode 100755 index 000000000..cb712ebd2 Binary files /dev/null and b/examples/sphinx/release/_static/favicon.ico differ diff --git a/examples/sphinx/release/_static/logo_onap_2017.png b/examples/sphinx/release/_static/logo_onap_2017.png new file mode 100644 index 000000000..5d064f431 Binary files /dev/null and b/examples/sphinx/release/_static/logo_onap_2017.png differ diff --git a/examples/sphinx/release/conf.py b/examples/sphinx/release/conf.py new file mode 100644 index 000000000..b2ba93216 --- /dev/null +++ b/examples/sphinx/release/conf.py @@ -0,0 +1,42 @@ +project = "onap" +release = "kohn" +version = "kohn" + +author = "Open Network Automation Platform" +# yamllint disable-line rule:line-length +copyright = "ONAP. Licensed under Creative Commons Attribution 4.0 International License" + +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 + +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 = 'kohn' + +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' + +def setup(app): + app.add_css_file("css/ribbon.css") diff --git a/examples/sphinx/release/images/biohazard.png b/examples/sphinx/release/images/biohazard.png new file mode 100644 index 000000000..ae4629d8b Binary files /dev/null and b/examples/sphinx/release/images/biohazard.png differ diff --git a/examples/sphinx/release/index.rst b/examples/sphinx/release/index.rst new file mode 100644 index 000000000..c7685a558 --- /dev/null +++ b/examples/sphinx/release/index.rst @@ -0,0 +1,132 @@ +===================================================== + The reStructuredText_ Cheat Sheet: Syntax Reminders +===================================================== +:Info: See for introductory docs. +:Author: David Goodger +:Date: $Date: 2021-03-05 22:14:40 +0100 (Fr, 05. Mär 2021) $ +:Revision: $Revision: 8631 $ +:Description: This is a "docinfo block", or bibliographic field list + +.. NOTE:: If you are reading this as HTML, please read + ``_ instead to see the input syntax examples! + +Section Structure +================= +Section titles are underlined or overlined & underlined. + +Body Elements +============= +Grid table: + ++--------------------------------+-----------------------------------+ +| Paragraphs are flush-left, | Literal block, preceded by "::":: | +| separated by blank lines. | | +| | Indented | +| Block quotes are indented. | | ++--------------------------------+ or:: | +| >>> print 'Doctest block' | | +| Doctest block | > Quoted | ++--------------------------------+-----------------------------------+ +| | Line blocks preserve line breaks & indents. [new in 0.3.6] | +| | Useful for addresses, verse, and adornment-free lists; long | +| lines can be wrapped with continuation lines. | ++--------------------------------------------------------------------+ + +Simple tables: + +================ ============================================================ +List Type Examples (syntax in the `text source `_) +================ ============================================================ +Bullet list * items begin with "-", "+", or "*" +Enumerated list 1. items use any variation of "1.", "A)", and "(i)" + #. also auto-enumerated +Definition list Term is flush-left : optional classifier + Definition is indented, no blank line between +Field list :field name: field body +Option list -o at least 2 spaces between option & description +================ ============================================================ + +================ ============================================================ +Explicit Markup Examples (visible in the `text source`_) +================ ============================================================ +Footnote .. [1] Manually numbered or [#] auto-numbered + (even [#labelled]) or [*] auto-symbol +Citation .. [CIT2002] A citation. +Hyperlink Target .. _reStructuredText: http://docutils.sf.net/rst.html + .. _indirect target: reStructuredText_ + .. _internal target: +Anonymous Target __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html +Directive ("::") .. image:: images/biohazard.png +Substitution Def .. |substitution| replace:: like an inline directive +Comment .. is anything else +Empty Comment (".." on a line by itself, with blank lines before & after, + used to separate indentation contexts) +================ ============================================================ + +Inline Markup +============= +*emphasis*; **strong emphasis**; `interpreted text`; `interpreted text +with role`:emphasis:; ``inline literal text``; standalone hyperlink, +http://docutils.sourceforge.net; named reference, reStructuredText_; +`anonymous reference`__; footnote reference, [1]_; citation reference, +[CIT2002]_; |substitution|; _`inline internal target`. + +Directive Quick Reference +========================= +See for full info. + +================ ============================================================ +Directive Name Description (Docutils version added to, in [brackets]) +================ ============================================================ +attention Specific admonition; also "caution", "danger", + "error", "hint", "important", "note", "tip", "warning" +admonition Generic titled admonition: ``.. admonition:: By The Way`` +image ``.. image:: picture.png``; many options possible +figure Like "image", but with optional caption and legend +topic ``.. topic:: Title``; like a mini section +sidebar ``.. sidebar:: Title``; like a mini parallel document +parsed-literal A literal block with parsed inline markup +rubric ``.. rubric:: Informal Heading`` +epigraph Block quote with class="epigraph" +highlights Block quote with class="highlights" +pull-quote Block quote with class="pull-quote" +compound Compound paragraphs [0.3.6] +container Generic block-level container element [0.3.10] +table Create a titled table [0.3.1] +list-table Create a table from a uniform two-level bullet list [0.3.8] +csv-table Create a table from CSV data [0.3.4] +contents Generate a table of contents +sectnum Automatically number sections, subsections, etc. +header, footer Create document decorations [0.3.8] +target-notes Create an explicit footnote for each external target +math Mathematical notation (input in LaTeX format) +meta Document metadata +include Read an external reST file as if it were inline +raw Non-reST data passed untouched to the Writer +replace Replacement text for substitution definitions +unicode Unicode character code conversion for substitution defs +date Generates today's date; for substitution defs +class Set a "class" attribute on the next element +role Create a custom interpreted text role [0.3.2] +default-role Set the default interpreted text role [0.3.10] +title Set the metadata document title [0.3.10] +================ ============================================================ + +Interpreted Text Role Quick Reference +===================================== +See for full info. + +================ ============================================================ +Role Name Description +================ ============================================================ +emphasis Equivalent to *emphasis* +literal Equivalent to ``literal`` but processes backslash escapes +math Mathematical notation (input in LaTeX format) +PEP Reference to a numbered Python Enhancement Proposal +RFC Reference to a numbered Internet Request For Comments +raw For non-reST data; cannot be used directly (see docs) [0.3.6] +strong Equivalent to **strong** +sub Subscript +sup Superscript +title Title reference (book, etc.); standard default role +================ ============================================================ diff --git a/examples/sphinx/release/requirements-docs.txt b/examples/sphinx/release/requirements-docs.txt new file mode 100644 index 000000000..dc55d67b4 --- /dev/null +++ b/examples/sphinx/release/requirements-docs.txt @@ -0,0 +1,8 @@ +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/release/tox.ini b/examples/sphinx/release/tox.ini new file mode 100644 index 000000000..6505b8512 --- /dev/null +++ b/examples/sphinx/release/tox.ini @@ -0,0 +1,77 @@ +[tox] +minversion = 1.6 +envlist = docs,docs-linkcheck +skipsdist = true + +[testenv:docs] +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 -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}/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 = + pylint --max-line-length=120 --disable=missing-docstring --reports=y --score=y --output-format=colorized docs/conf.py -- cgit 1.2.3-korg