Documentation QA Tests

[svx]

'Just' for fun I run my most basic test script against the docs of plone.restapi, basically the script tries only to build the docs with Sphinx in nit-picky mode and turns warnings into errors.

  svx  ⓔ  plone.restapi   svx_docs1  ~  Projects  plone  plone.restapi  ./run_tests.sh 
--> Starting build for /home/svx/Projects/plone/plone.restapi/docs/source
Running Sphinx v1.5.3
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 21 source files that are out of date
updating environment: 21 added, 0 changed, 0 removed
...
...
Build finished. The HTML pages are in _build/html.
SPHINX ERRORS: 137

********** All builds done ************
TOTAL SPHINX ERRORS: 137
OTHER BUILD ERRORS: 0
There were problems while building the following projects:
docs/source

Besides a lot of reST syntax errors , some typos and wording issues this needs fixing :)

The origin of most of these errors is the 'mis-use' of sphinxcontrib-osexample which was never intended for this.
In order to solve this sphinxcontrib-osexample, needs fixing of the missing lexer, or the removal of all lexer, which should IMHO the better solution, since there may be more additions in the future :).

Further on you need to add some files to the index or declare in your conf.py that these files should be ignored.

To Do:

• fix reST
• fix typos
• fix docs structure
• fix lexer

If you feel now this is not important, no offense but I am really sorry, I disagree.

We are busy moving our docs to a new test, build and hosting infra and currently these docs [also others :)] are failing all tests.