How to use sphinx with Kivy

[Yoel Koenka]

Following up on this thread:
https://mail.google.com/mail/u/0/#inbox/14f09cfb4a235fe0

I have a kivy project that uses kivy-garden libraries (such as graph).
When I try to build sphinx documentation, it miserably fails, but only when the garden libraries are used.
The problem is that sphinx doesn't know to use kivy as the python interpreter.

I'm sure someone here has had success with this, can you please give me a hint?

Thanks a lot!
Joel

[ZenCODE]

If you use the kivy.bat file or interpreter to launch the sphinx script, it should pick up all you kivy libraries? When I first tried, we had issue with the Window being None, but you can use

    if 'KIVY_DOC' not in os.environ:

to skip these parts.You may need to plug that variable into your own environment as that's set as part of Kivys' build process...

Peace out

[Yoel Koenka]

Thank you ZenCODE!

Sorry for not replying so long... I'll give it a try

--
You received this message because you are subscribed to a topic in the Google Groups "Kivy users support" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/kivy-users/xuEXWFWoYwo/unsubscribe.
To unsubscribe from this group and all its topics, send an email to kivy-users+...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Bret H]

ZenCODE,
I've been working with Yoel on the same project and adding that line works, but doing this for all the places that are affecting our the Sphinx docs might be troublesome.  I traced it down and made an example kivy app/script (a.k.a. "main.py") that shows the basic issue that is affecting the garden module (it's the garden.graph module)

The code below runs fine via "python ./main.py". It just opens a Kivy app window with nothing in it.

from kivy.app import App
from kivy.uix.widget import Widget

class MyClass(Widget):
    def __init__(self, **kwargs):
        super(MyClass,  self).__init__(**kwargs)

class MyDocTestApp(App):
    '''The main application
    '''
    test = MyClass()


if __name__ == '__main__':
    app = MyDocTestApp()
    app.run()

When running Sphinx against this code  I would expect some Sphinx html documents with a the docs for "MyDocTestApp" in them.

FYI: The Sphinx docs are being generated via:
1. One time only: run "sphinx-quickstart" with some options. This is done one time only to quickly generate the generic Sphinx documentation files/templates.

2. One time only: make some modifications to the Sphinx conf.py file, mostly so it will properly reference the python/kivy project directory to document.

3. sphinx-apidoc with some options is run to rebuild the documentation trees/etc.

4. "make html" is run to build the documentation

When executing "make html" The failure that occurs (that causes the documemtation to have no content) is:
[CRITICAL] [App         ] Unable to get a Window, abort.                      

/<path to my Sphinx templates>/main.rst:4: WARNING: autodoc: failed to import module u'main'; the module executes module level statement and it might call sys.exit().

If I replace this line of code:
super(MyClass,  self).__init__(**kwargs)
with:
pass

there are no errors and the Sphinx html documentation generates correctly. Any ideas what is causing Sphinx to choke on this line.?

I traced down the error message in the Sphinx package and it's using "__import__"

[Bret H]

I accidentally posted before finishing... sorry :)

"I traced down the error message in the Sphinx package and it's using "__import__"".... to load the python module(s) and the error is being caught because the import fails.

I'm not sure if this is the correct place to post this, since it's more of a Sphinx issue specific to just Kivy, so if anyone knows of a better place/forum I'd be grateful if you could point me in the right direction.

[ZenCODE]

Are you sure you are setting that environment variable before you do any importing? i.e.

    import os
    os.environ['KIVY_DOC'] = '1'
    # or os.environ['KIVY_DOC_INCLUDE'] = '1' ??

should before you do any other importing?

[Bret H]

In my example above, I could do this like so:

import os
os.environ['KIVY_DOC'] = '1'

(other importing)

(MyClass definition)

class MyDocTestApp(App):
    '''The main application
    '''
   

if 'KIVY_DOC' not in os.environ:


    test = MyClass()


if 'KIVY_DOC' not in os.environ:

test = MyClass()


--
You received this message because you are subscribed to the Google Groups "Kivy users support" group.
To unsubscribe from this group and stop receiving emails from it, send an email to kivy-users+...@googlegroups.com.

[Bret H]

Sorry, I accidentally sent before finishing...I was trying to format it nicely :)

Anyway: I could comment out the creation of the MyClass instance by commenting out that line:

if 'KIVY_DOC' not in os.environ:
    test = MyClass()



or even do it on the line that causes the issues:


if 'KIVY_DOC' not in os.environ:

    super(MyClass,  self).__init__(**kwargs)




And in this example the problem would go away, but that would mean we'd have to do this in many places in our code as opposed to this simple example. It seems that only the kivy garden.graph module has this issue, so I figured that maybe they had done something not-so-kivyish in their Class definition, which is essentially this (their class definition is much larger of course):


class MyClass(Widget):
    def __init__(self, **kwargs):
        super(MyClass,  self).__init__(**kwargs)



If the kivy.garden module was doing somehitng less than correct, I'd rather recommend a patch (if I even could figure it out) of request a bug fix to the module than patch our code to get around it.