search

vovkos / doxyrest

A compiler from Doxygen XML to reStructuredText -- hence, the name. It parses XML databases generated by Doxygen and produces reStructuredText for the Python documentation generator Sphinx.
MIT License
306 stars 23 forks source link

Doxyrest doesn't work with Sphnix 3.x #30

Closed ceandrade closed 4 years ago

ceandrade commented 4 years ago

Hi,

I'm using sphinx-build 3.0.1 and it cannot load the doxyrest plugin:

$ sphinx-build -b html build/rst build/html_sphinx
Running Sphinx v3.0.1

Extension error:
Could not import extension doxyrest (exception: cannot import name 'SphinxBaseFileInput' from 'sphinx.io' (unknown location))

Cheking the site-package, I couldn't find SphinxBaseFileInput:

$ pwd
/opt/local/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/sphinx

$ grep -R SphinxBaseFileInput *
$

And, indeed, according to the following link, SphinxBaseFileInput is deprecated on version 2.x:

https://www.sphinx-doc.org/en/master/changes.html

Thanks!

vovkos commented 4 years ago

Okay, so they finally removed it :D Oh well... I guess it was time to update the Doxyrest extension for Sphinx 3...

This commit takes care of the issue. There are two more commits after that to maintain compatibility with Python 2. Just pull master and try if it works for you. Only the Sphinx extension has changed, so no need to rebuild the executable.

I plan to make a tagged release tomorrow (it's about time), so please do let me know if you find any issues with the fix.

ceandrade commented 4 years ago

That works my friend! Many thanks! I have no complain for the time being. By curiosity, this is the documentation I'm generating:

https://ceandrade.github.io/brkga_mp_ipr_cpp

Thanks again for this great work!

vovkos commented 4 years ago

Glad it works for you :) And your docs are looking good!

A small thing though -- I noticed param lists sometimes don't fit into the screen width allotted by sphinx_rtd_theme. You can try playing with ML_PARAM_LIST_LENGTH_THRESHOLD to wrap param lists upon reaching some length.

ceandrade commented 4 years ago

Thanks! I tried to spot such issue, but I couldn't. I have changed ML_PARAM_LIST_LENGTH_THRESHOLD on doxyrest-config.lua but I haven't notice significative change. Well, maybe I didn't spend enough time searching. If you can point me one case, I'll be glad.

Many thanks again!

vovkos commented 4 years ago

I've just made a push to make ML_PARAM_LIST_LENGTH_THRESHOLD more predictable. Previously, it didn't remove :ref: and :target: roles out of declarations, so it was a bit hard to predict whether a particular parameter list will wrap or not (maybe, that's the reason it didn't work for you).

Here's a simple example to demonstrate ML_PARAM_LIST_LENGTH_THRESHOLD:

param_wrap_test.zip

Play with ML_PARAM_LIST_LENGTH_THRESHOLD and see when parameter-lists start to wrap.