Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
3 tasks
rclations opened this issue Aug 10, 2017 · 6 comments
Closed
3 tasks

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

rclations opened this issue Aug 10, 2017 · 6 comments

Comments

@rclations
Copy link

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 rclations added this to the 0.6 - Performance & SEO milestone Aug 10, 2017
@rclations
Copy link
Author

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

@benlk
Copy link
Collaborator

benlk commented Jul 10, 2018

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 benlk changed the title Convert Docs to Github Wiki Pages Convert Docs from .rst to .md, remove Sphinx and related python Nov 9, 2018
@benlk benlk modified the milestones: 0.6.1 - Bugfixes, 0.6.2 Dec 7, 2018
@benlk
Copy link
Collaborator

benlk commented Dec 7, 2018

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:

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
Copy link
Collaborator

benlk commented Apr 22, 2019

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
Copy link
Collaborator

benlk commented Apr 22, 2019

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
Copy link
Collaborator

benlk commented Apr 22, 2019

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants