From 3093269296e267427debd31e180ac29fcab349df Mon Sep 17 00:00:00 2001 From: Cédric Ollivier Date: Mon, 22 Nov 2021 14:21:29 +0100 Subject: Make examples buildable MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit It now excludes .tox from conf.py. It locally clones docutils cheatsheet as examples (it should be noted that cheatsheet.txt is renamed index.rst in it). [1] https://docutils.sourceforge.io/docs/user/rst/cheatsheet.txt Issue-ID: DOC-772 Signed-off-by: Cédric Ollivier Change-Id: Ifd616b797d5a48da5df77b0dfaa0613497b742d8 --- .gitignore | 1 + examples/sphinx/.readthedocs.yaml | 20 ---- examples/sphinx/README.md | 72 ++++------- examples/sphinx/conf.py_MASTER | 15 --- examples/sphinx/conf.py_NEWBRANCH | 15 --- examples/sphinx/istanbul/_static/css/ribbon.css | 63 ++++++++++ examples/sphinx/istanbul/_static/favicon.ico | Bin 0 -> 2102 bytes .../sphinx/istanbul/_static/logo_onap_2017.png | Bin 0 -> 12278 bytes examples/sphinx/istanbul/conf.py | 19 +++ examples/sphinx/istanbul/conf.yaml | 7 ++ examples/sphinx/istanbul/images/biohazard.png | Bin 0 -> 179 bytes examples/sphinx/istanbul/index.rst | 132 +++++++++++++++++++++ examples/sphinx/istanbul/requirements-docs.txt | 1 + examples/sphinx/istanbul/tox.ini | 25 ++++ examples/sphinx/master/_static/css/ribbon.css | 63 ++++++++++ examples/sphinx/master/_static/favicon.ico | Bin 0 -> 2102 bytes examples/sphinx/master/_static/logo_onap_2017.png | Bin 0 -> 12278 bytes examples/sphinx/master/conf.py | 19 +++ examples/sphinx/master/conf.yaml | 7 ++ examples/sphinx/master/images/biohazard.png | Bin 0 -> 179 bytes examples/sphinx/master/index.rst | 132 +++++++++++++++++++++ examples/sphinx/master/requirements-docs.txt | 1 + examples/sphinx/master/tox.ini | 25 ++++ examples/sphinx/requirements-docs.txt | 1 - examples/sphinx/tox.ini_MASTER | 25 ---- examples/sphinx/tox.ini_NEWBRANCH | 25 ---- 26 files changed, 518 insertions(+), 150 deletions(-) delete mode 100644 examples/sphinx/.readthedocs.yaml delete mode 100644 examples/sphinx/conf.py_MASTER delete mode 100644 examples/sphinx/conf.py_NEWBRANCH create mode 100644 examples/sphinx/istanbul/_static/css/ribbon.css create mode 100755 examples/sphinx/istanbul/_static/favicon.ico create mode 100644 examples/sphinx/istanbul/_static/logo_onap_2017.png create mode 100644 examples/sphinx/istanbul/conf.py create mode 100644 examples/sphinx/istanbul/conf.yaml create mode 100644 examples/sphinx/istanbul/images/biohazard.png create mode 100644 examples/sphinx/istanbul/index.rst create mode 100644 examples/sphinx/istanbul/requirements-docs.txt create mode 100644 examples/sphinx/istanbul/tox.ini create mode 100644 examples/sphinx/master/_static/css/ribbon.css create mode 100755 examples/sphinx/master/_static/favicon.ico create mode 100644 examples/sphinx/master/_static/logo_onap_2017.png create mode 100644 examples/sphinx/master/conf.py create mode 100644 examples/sphinx/master/conf.yaml create mode 100644 examples/sphinx/master/images/biohazard.png create mode 100644 examples/sphinx/master/index.rst create mode 100644 examples/sphinx/master/requirements-docs.txt create mode 100644 examples/sphinx/master/tox.ini delete mode 100644 examples/sphinx/requirements-docs.txt delete mode 100644 examples/sphinx/tox.ini_MASTER delete mode 100644 examples/sphinx/tox.ini_NEWBRANCH diff --git a/.gitignore b/.gitignore index 3371e590b..93bb8772d 100644 --- a/.gitignore +++ b/.gitignore @@ -9,6 +9,7 @@ __pycache__/ # Distribution / packaging .Python build/ +_build develop-eggs/ dist/ downloads/ diff --git a/examples/sphinx/.readthedocs.yaml b/examples/sphinx/.readthedocs.yaml deleted file mode 100644 index 82889b5ac..000000000 --- a/examples/sphinx/.readthedocs.yaml +++ /dev/null @@ -1,20 +0,0 @@ ---- -# .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 index e8decf9a4..ababb3834 100644 --- a/examples/sphinx/README.md +++ b/examples/sphinx/README.md @@ -3,64 +3,38 @@ 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 +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. -##### USE: -in MASTER branch of your repository -##### PATH: -{project}/docs -##### TODO: -remove _MASTER from filename +The additional directories named *_static* and *images* and the file +*index.rst* are required to make the examples buildable. In the respective +directory you can execute the '*tox -e docs*' command and the build starts. -## FILE: tox.ini_NEWBRANCH +## FILE: conf.py +##### DESCRIPTION: +The “build configuration file” contains (almost) all configuration needed to +customize Sphinx input and output behavior. -##### 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.yaml +##### DESCRIPTION: +todo -## 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 +##### DESCRIPTION: +todo -##### USE: -in both, MASTER branch and 'NEWBRANCH' of your repository -##### PATH: -{project}/docs -##### TODO: -– ## FILE: .readthedocs.yaml +##### DESCRIPTION: +todo + -##### USE: -in both, MASTER branch and 'NEWBRANCH' of your repository -##### PATH: -{project} -##### TODO: -– +## FILE: tox.ini +##### DESCRIPTION: +todo \ No newline at end of file diff --git a/examples/sphinx/conf.py_MASTER b/examples/sphinx/conf.py_MASTER deleted file mode 100644 index d211470a6..000000000 --- a/examples/sphinx/conf.py_MASTER +++ /dev/null @@ -1,15 +0,0 @@ -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 deleted file mode 100644 index ea67c5518..000000000 --- a/examples/sphinx/conf.py_NEWBRANCH +++ /dev/null @@ -1,15 +0,0 @@ -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/istanbul/_static/css/ribbon.css b/examples/sphinx/istanbul/_static/css/ribbon.css new file mode 100644 index 000000000..6008cb1a0 --- /dev/null +++ b/examples/sphinx/istanbul/_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: none; +} diff --git a/examples/sphinx/istanbul/_static/favicon.ico b/examples/sphinx/istanbul/_static/favicon.ico new file mode 100755 index 000000000..cb712ebd2 Binary files /dev/null and b/examples/sphinx/istanbul/_static/favicon.ico differ diff --git a/examples/sphinx/istanbul/_static/logo_onap_2017.png b/examples/sphinx/istanbul/_static/logo_onap_2017.png new file mode 100644 index 000000000..5d064f431 Binary files /dev/null and b/examples/sphinx/istanbul/_static/logo_onap_2017.png differ diff --git a/examples/sphinx/istanbul/conf.py b/examples/sphinx/istanbul/conf.py new file mode 100644 index 000000000..1d6c7d357 --- /dev/null +++ b/examples/sphinx/istanbul/conf.py @@ -0,0 +1,19 @@ +from docs_conf.conf import * + +branch = 'istanbul' +master_doc = 'index' + +linkcheck_ignore = [ + 'http://localhost', +] + +exclude_patterns = [ + '.tox' +] + +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/istanbul/conf.yaml b/examples/sphinx/istanbul/conf.yaml new file mode 100644 index 000000000..44de212d1 --- /dev/null +++ b/examples/sphinx/istanbul/conf.yaml @@ -0,0 +1,7 @@ +--- +project_cfg: onap +project: onap + +# Change this to ReleaseBranchName to modify the header +default-version: istanbul +# diff --git a/examples/sphinx/istanbul/images/biohazard.png b/examples/sphinx/istanbul/images/biohazard.png new file mode 100644 index 000000000..ae4629d8b Binary files /dev/null and b/examples/sphinx/istanbul/images/biohazard.png differ diff --git a/examples/sphinx/istanbul/index.rst b/examples/sphinx/istanbul/index.rst new file mode 100644 index 000000000..c7685a558 --- /dev/null +++ b/examples/sphinx/istanbul/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/istanbul/requirements-docs.txt b/examples/sphinx/istanbul/requirements-docs.txt new file mode 100644 index 000000000..74a3b7a3f --- /dev/null +++ b/examples/sphinx/istanbul/requirements-docs.txt @@ -0,0 +1 @@ +lfdocs-conf diff --git a/examples/sphinx/istanbul/tox.ini b/examples/sphinx/istanbul/tox.ini new file mode 100644 index 000000000..8b5bc99bf --- /dev/null +++ b/examples/sphinx/istanbul/tox.ini @@ -0,0 +1,25 @@ +[tox] +minversion = 1.6 +envlist = docs,docs-linkcheck +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 -W -b html -n -d {envtmpdir}/doctrees ./ {toxinidir}/_build/html + echo "Generated docs available in {toxinidir}/_build/html" +whitelist_externals = + echo + +[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 +commands = + sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees ./ {toxinidir}/_build/linkcheck diff --git a/examples/sphinx/master/_static/css/ribbon.css b/examples/sphinx/master/_static/css/ribbon.css new file mode 100644 index 000000000..6008cb1a0 --- /dev/null +++ b/examples/sphinx/master/_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: none; +} diff --git a/examples/sphinx/master/_static/favicon.ico b/examples/sphinx/master/_static/favicon.ico new file mode 100755 index 000000000..cb712ebd2 Binary files /dev/null and b/examples/sphinx/master/_static/favicon.ico differ diff --git a/examples/sphinx/master/_static/logo_onap_2017.png b/examples/sphinx/master/_static/logo_onap_2017.png new file mode 100644 index 000000000..5d064f431 Binary files /dev/null and b/examples/sphinx/master/_static/logo_onap_2017.png differ diff --git a/examples/sphinx/master/conf.py b/examples/sphinx/master/conf.py new file mode 100644 index 000000000..e782429a1 --- /dev/null +++ b/examples/sphinx/master/conf.py @@ -0,0 +1,19 @@ +from docs_conf.conf import * + +branch = 'latest' +master_doc = 'index' + +linkcheck_ignore = [ + 'http://localhost', +] + +exclude_patterns = [ + '.tox' +] + +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/master/conf.yaml b/examples/sphinx/master/conf.yaml new file mode 100644 index 000000000..ab5928131 --- /dev/null +++ b/examples/sphinx/master/conf.yaml @@ -0,0 +1,7 @@ +--- +project_cfg: onap +project: onap + +# Change this to ReleaseBranchName to modify the header +default-version: latest +# diff --git a/examples/sphinx/master/images/biohazard.png b/examples/sphinx/master/images/biohazard.png new file mode 100644 index 000000000..ae4629d8b Binary files /dev/null and b/examples/sphinx/master/images/biohazard.png differ diff --git a/examples/sphinx/master/index.rst b/examples/sphinx/master/index.rst new file mode 100644 index 000000000..c7685a558 --- /dev/null +++ b/examples/sphinx/master/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/master/requirements-docs.txt b/examples/sphinx/master/requirements-docs.txt new file mode 100644 index 000000000..74a3b7a3f --- /dev/null +++ b/examples/sphinx/master/requirements-docs.txt @@ -0,0 +1 @@ +lfdocs-conf diff --git a/examples/sphinx/master/tox.ini b/examples/sphinx/master/tox.ini new file mode 100644 index 000000000..9057fb77f --- /dev/null +++ b/examples/sphinx/master/tox.ini @@ -0,0 +1,25 @@ +[tox] +minversion = 1.6 +envlist = docs,docs-linkcheck +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 -W -b html -n -d {envtmpdir}/doctrees ./ {toxinidir}/_build/html + echo "Generated docs available in {toxinidir}/_build/html" +whitelist_externals = + echo + +[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 +commands = + sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees ./ {toxinidir}/_build/linkcheck diff --git a/examples/sphinx/requirements-docs.txt b/examples/sphinx/requirements-docs.txt deleted file mode 100644 index 74a3b7a3f..000000000 --- a/examples/sphinx/requirements-docs.txt +++ /dev/null @@ -1 +0,0 @@ -lfdocs-conf diff --git a/examples/sphinx/tox.ini_MASTER b/examples/sphinx/tox.ini_MASTER deleted file mode 100644 index c5ed11775..000000000 --- a/examples/sphinx/tox.ini_MASTER +++ /dev/null @@ -1,25 +0,0 @@ -[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 deleted file mode 100644 index 8b0a0fa04..000000000 --- a/examples/sphinx/tox.ini_NEWBRANCH +++ /dev/null @@ -1,25 +0,0 @@ -[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