Convert Docs from .rst to .md, remove Sphinx and related python

[rclations]

Currently the theme docs are hosted in the theme in the /docs folder, using RST files that are parsed into html files using Python and hosted at http://largo.readthedocs.io/

This ticket will achieve 3 things:

• Help us remove Python from our PHP WordPress Theme
• Put the docs in a more familiar place where anyone can contribute
• Take the docs out of the theme directory, helping to make the theme a little leaner.

ToDo:

• The wiki is currently filled with an old version of the docs from 2014 - first, let's delete all these pages.
• Copy the doc files into Github Wiki pages
• Delete the .rst files as they're moved into the wiki

[rclations]

Please do not delete https://github.com/INN/largo/wiki/Sites-Using-Largo

[benlk]

I agree on removing python from the theme, but I also think that keeping the theme and the docs at the same version number in the same repository is better than having docs be separate from the code.

• convert .rst to .md in place.

[benlk]

Discovered while working on #1359, reviewing https://largo.readthedocs.io/developers/setup-documentation.html, the following commands do not run:

• grunt apidocs and grunt shell:apidocs:

  $ grunt apidocs
  Running "shell:apidocs" (shell) task
  Building .rst files
  python generate_api_docs.py
  PHP Fatal error: Uncaught TypeError: Argument 2 passed to DoxPHP\Parser\Parser::parseBlock() must be an instance of DoxPHP\Parser\stdClass, instance of stdClass given, called in /Users/blk/.pear/share/pear/DoxPHP/Parser/Parser.php on line 45 and defined in /Users/blk/.pear/share/pear/DoxPHP/Parser/Parser.php:59
  Stack trace:
  #0 /Users/blk/.pear/share/pear/DoxPHP/Parser/Parser.php(45): DoxPHP\Parser\Parser->parseBlock(Object(DoxPHP\Parser\Tokens), Object(stdClass))
  Aschweigert #1 /Users/blk/.pear/bin/doxphp(22): DoxPHP\Parser\Parser->parse(Object(DoxPHP\Parser\Tokens))
  Aschweigert #2 {main}
  thrown in /Users/blk/.pear/share/pear/DoxPHP/Parser/Parser.php on line 59
  Traceback (most recent call last):
  File "generate_api_docs.py", line 82, in
  process.main()
  File "generate_api_docs.py", line 73, in main
  response = subprocess.check_output(['doxphp < %s' % src], shell=True)
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/subprocess.py", line 573, in check_output
  raise CalledProcessError(retcode, cmd, output=output)
  subprocess.CalledProcessError: Command '['doxphp < ../functions.php']' returned non-zero exit status 255
  make: *** [php] Error 1
  Warning: Command failed: cd docs&&rm -Rf api _build/html/api _build/doctrees/api&&make php
  PHP Fatal error: Uncaught TypeError: Argument 2 passed to DoxPHP\Parser\Parser::parseBlock() must be an instance of DoxPHP\Parser\stdClass, instance of stdClass given, called in /Users/blk/.pear/share/pear/DoxPHP/Parser/Parser.php on line 45 and defined in /Users/blk/.pear/share/pear/DoxPHP/Parser/Parser.php:59
  Stack trace:
  #0 /Users/blk/.pear/share/pear/DoxPHP/Parser/Parser.php(45): DoxPHP\Parser\Parser->parseBlock(Object(DoxPHP\Parser\Tokens), Object(stdClass))
  Aschweigert #1 /Users/blk/.pear/bin/doxphp(22): DoxPHP\Parser\Parser->parse(Object(DoxPHP\Parser\Tokens))
  Aschweigert #2 {main}
  thrown in /Users/blk/.pear/share/pear/DoxPHP/Parser/Parser.php on line 59
  Traceback (most recent call last):
  File "generate_api_docs.py", line 82, in
  process.main()
  File "generate_api_docs.py", line 73, in main
  response = subprocess.check_output(['doxphp < %s' % src], shell=True)
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/subprocess.py", line 573, in check_output
  raise CalledProcessError(retcode, cmd, output=output)
  subprocess.CalledProcessError: Command '['doxphp < ../functions.php']' returned non-zero exit status 255
  make: * [php] Error 1
  Use --force to continue.

  Aborted due to warnings.

  Execution Time (2018-12-06 23:19:30 UTC-5)
  loading tasks 5ms ▇ 1%
  shell:apidocs 396ms ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 99%
  Total 401ms

• grunt shell:sphinx:

  $ grunt shell:sphinx
  Running "shell:sphinx" (shell) task
  sphinx-build -b html -d _build/doctrees . _build/html
  Making output directory...
  Running Sphinx v1.2.3
  loading pickled environment... not yet created
  building [html]: targets for 66 source files that are out of date
  updating environment: 66 added, 0 changed, 0 removed
  reading sources... [ 1%] api/archive
  reading sources... [ 3%] api/feed-mailchimp
  reading sources... [ 4%] api/functions
  reading sources... [ 6%] api/homepages/homepage
  reading sources... [ 7%] api/homepages/layouts/HomepageSingleWithSeriesStories
  reading sources... [ 9%] api/homepages/zones/zones
  reading sources... [ 10%] api/inc/ajax-functions
  reading sources... [ 12%] api/inc/avatars
  reading sources... [ 13%] api/inc/avatars/functions
  reading sources... [ 15%] api/inc/byline_class

  Exception occurred:
  File "/Users/blk/.virtualenvs/largo/lib/python2.7/site-packages/sphinxcontrib/phpdomain.py", line 144, in handle_signature
  classname = classname.rstrip('::')
  AttributeError: 'NoneType' object has no attribute 'rstrip'
  The full traceback has been saved in /var/folders/3j/x3hprpwd11b39vwddy435rp80000gn/T/sphinx-err-HRaVOH.log, if you want to report the issue to the developers.
  Please also report this if it was a user error, so that a better error message can be provided next time.
  A bug report can be filed in the tracker at https://bitbucket.org/birkenfeld/sphinx/issues/. Thanks!
  None
  Largo_Byline::
  make: *** [html] Error 1
  Warning: Command failed: cd docs&&make html

  Exception occurred:
  File "/Users/blk/.virtualenvs/largo/lib/python2.7/site-packages/sphinxcontrib/phpdomain.py", line 144, in handle_signature
  classname = classname.rstrip('::')
  AttributeError: 'NoneType' object has no attribute 'rstrip'
  The full traceback has been saved in /var/folders/3j/x3hprpwd11b39vwddy435rp80000gn/T/sphinx-err-HRaVOH.log, if you want to report the issue to the developers.
  Please also report this if it was a user error, so that a better error message can be provided next time.
  A bug report can be filed in the tracker at https://bitbucket.org/birkenfeld/sphinx/issues/. Thanks!
  make: * [html] Error 1
  Use --force to continue.

  Aborted due to warnings.

  Execution Time (2018-12-06 23:22:03 UTC-5)
  shell:sphinx 1.1s ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 100%
  Total 1.1s

Other items:

• Add pip requirements.txt for the things required by Grunt, update various docs #1585 will replace the grunt-pot dependency with a wp-cli task: https://developer.wordpress.org/cli/commands/i18n/make-pot/

The md docs can be served from github; what we really need here is a working apidocs function to make the php docblocs into markdown or rst.

[benlk]

The ReadTheDocs GitHub hook has been updated for #1616, but the build is failing for the branch that allows the new ReadTheDocs build to build. (#1616).

Our API docs are generated by grunt apidocs, which is an alias for the grunt shell:apidocs command that, according to our documentation, "Converts all available reStructuredText files into HTML documentation, which is saved locally in docs/_build/html/. If you want to preview these docs without pushing them to largo.readthedocs.io, run python -m SimpleHTTPServer as described in the documentation contribution instructions."

The shell:sphinx command:

https://github.com/INN/largo/blob/d395c395f425351e528c123a5de207e12fb74899/Gruntfile.js#L94-L98

make php does this:

https://github.com/INN/largo/blob/d395c395f425351e528c123a5de207e12fb74899/docs/Makefile#L179-L181

That python script docs/generate_api_docs.py in turn uses shell code to run doxphp < input.php | doxphp2sphinx > output.rst, and if you're wondering where doxphp comes from, the long story is that it's in our developer documentation (currently not available because the ReadTheDocs build is failing) but can also be found in GitHub at https://github.com/INN/largo/tree/0.5-dev/docs/developers

tl;dr: it's https://github.com/avalanche123/doxphp , last updated ... 6 months ago. huh. That's earlier than I thought.

[benlk]

Okay, can fix that step in the build by upgrading to latest doxphp.

The PEAR server isn't available, so I've filed a bug about that: avalanche123/doxphp#14

The PR for #1616 will have an update to the install instructions to solve the install problem.

[benlk]

And the ReadTheDocs build now passes, with the changes in #1680.