From 3beeced464fd424bda372d098a3b907f577d4155 Mon Sep 17 00:00:00 2001 From: Rich Bennett Date: Mon, 18 Sep 2017 10:01:25 -0400 Subject: [PATCH 1/1] Remove linkcheck and add API examples Part 1 of moviing linkcheck from verify to a CSIT job Added API examples and extensions used to document APIs Change-Id: I5dd536c50930b09bb129e95a9767c97f09c0604b Issue-ID: DOC-82 Signed-off-by: Rich Bennett --- docs/conf.py | 8 +++++++- docs/release/repolist.rst | 2 +- docs/templates/platform-component/offeredapis.rst | 23 ++++++++++++++++++++--- etc/requirements.txt | 3 +++ tox.ini | 4 ++-- 5 files changed, 33 insertions(+), 7 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index ceb28cad2..ff9deae86 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -37,7 +37,12 @@ extensions = [ 'sphinx.ext.imgmath', 'sphinx.ext.viewcode', 'sphinxcontrib.blockdiag', - 'sphinxcontrib.seqdiag' + 'sphinxcontrib.seqdiag', + 'sphinx.ext.ifconfig', + 'sphinx.ext.todo', + 'sphinxcontrib.httpdomain', + 'sphinxcontrib.plantuml', + 'sphinxcontrib.swaggerdoc' ] # Font path for seqdiag @@ -369,3 +374,4 @@ epub_exclude_files = ['search.html'] # Patterns to ignore in linkcheck builder linkcheck_ignore = [r'http://localhost:\d+/'] + diff --git a/docs/release/repolist.rst b/docs/release/repolist.rst index 96fdc551b..5c188d0e9 100644 --- a/docs/release/repolist.rst +++ b/docs/release/repolist.rst @@ -22,4 +22,4 @@ Documentation organized by the project delivering them. aai/search-data-service <../submodules/aai/search-data-service.git/docs/index> optf/has <../submodules/optf/has.git/docs/index> dcaegen2 <../submodules/dcaegen2.git/docs/index> - aaf/authz <../submodules/aaf/authz.git/docs/index> + aaf/authz <../submodules/aaf/authz.git/docs/index> diff --git a/docs/templates/platform-component/offeredapis.rst b/docs/templates/platform-component/offeredapis.rst index 3e3b5b3d0..55e58bd9b 100644 --- a/docs/templates/platform-component/offeredapis.rst +++ b/docs/templates/platform-component/offeredapis.rst @@ -6,7 +6,24 @@ Offered APIs ============ List APIs offered. One or more of the following examples may be appropriate. -* java docs link -* rest API swagger json definition displayed with sphinx directive .. swaggerv2doc: -* a restructured text document +Example Swagger Displayed with swaggerv2doc directive +----------------------------------------------------- +.. swaggerv2doc:: https://gerrit.onap.org/r/gitweb?p=vfc/nfvo/lcm.git;a=blob_plain;f=lcm/swagger/vfc.nslcm.swagger.json + + +Example documenting a REST interface with Sphinx httpdomain directive +--------------------------------------------------------------------- + +.. http:get:: path + + For more information see ``_ + + +Word Document Converted to RST using Pandocs +-------------------------------------------- + +.. toctree:: + :maxdepth: 1 + + ../../submodules/appc.git/docs/APPC API Guide/APPC API Guide diff --git a/etc/requirements.txt b/etc/requirements.txt index b12395a93..66f761074 100644 --- a/etc/requirements.txt +++ b/etc/requirements.txt @@ -7,4 +7,7 @@ six sphinxcontrib-httpdomain sphinxcontrib-blockdiag sphinxcontrib-seqdiag +sphinxcontrib-swaggerdoc +sphinxcontrib-plantuml +sphinxcontrib-httpdomain sphinx_bootstrap_theme>=0.4.11 diff --git a/tox.ini b/tox.ini index c1993d9ee..e3349e5a5 100644 --- a/tox.ini +++ b/tox.ini @@ -1,6 +1,6 @@ [tox] minversion = 1.6 -envlist = docs,docs-linkcheck +envlist = docs skipsdist = true [testenv:docs] @@ -12,4 +12,4 @@ whitelist_externals = echo [testenv:docs-linkcheck] deps = -r{toxinidir}/etc/requirements.txt -commands = sphinx-build -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck \ No newline at end of file +commands = sphinx-build -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck -- 2.16.6