Sphinx help

[Mark Jackson]

I'm finally getting Sphinx hooked up to the Red9 api and had a few questions to those of you running it in terms of formatting.

Firstly any code I have that's decorated doesn't get documented other than it's name, is there a trick or setting to get Sphinx to pass over the decorator into the code itself?

Secondly and I'm assuming there must be a way. In my function I'm doing the standard :param name: etc which generates a big pink block of params for the function, great, but these params are twice as bold as the functions and class names themselves, how can I make sure that the class header is boldest, and the function bold. Seems odd that the params come out bolder and more obvious than the function they're describing.

I'm assuming I'm missing a few things, only got this stuff running on Saturday.

thanks

Mark 

-------------------------------------
Mark Jackson
Technical Animation Director
http://markj3d.blogspot.com/

[Justin Israel]

Hey Mark,

Can you post some examples of both your .rst and a class + docstring?

I'm using sphinx for a few projects as well, and will use a mixture of both the autodoc features, and the manual stuff. The autodoc module/class features have properties that can control what it documents. In one of my projects many of the functions are decorated, but I am actually using autofunction on each one.

Maybe this link is relevant?

http://stackoverflow.com/questions/3687046/python-sphinx-autodoc-and-decorated-members

-- justin

--
You received this message because you are subscribed to the Google Groups "Python Programming for Autodesk Maya" group.
To unsubscribe from this group and stop receiving emails from it, send an email to python_inside_m...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/CAGQH2FHmUKZG08EO_Vpyus73Rze%3DibNKnUd05ndS1ps%2BPSdmMQ%40mail.gmail.com.
For more options, visit https://groups.google.com/groups/opt_out.

[Mark Jackson]

Sure, I'm only really just getting into it, looking at what we did at Eurocom and taking it from there. I want to try and get a good standard sorted before we push the same setups through our pipeline at work.

class MetaClass(object):

           

def __init__(self, node=None, name=None, nodeType='network', autofill='all', **kws):

        '''

        Base Class for Meta support. This manages all the attribute and class 

        management for all subsequent inherited classes.

        

        :param node: Maya Node - if given we test it for the mClass attribute, if it exists 

                we initialize a class of that type and return. If not passed in then we 

                make a new network node for the type given.

        :param name: only used on create, name to set for the new Maya Node (self.mNode)

        :param nodeType: allows you to specify a node of type to create as a new mClass node. 

                default is 'network', not that for any node to show up in the get 

                calls that type MUST be registered in the RED9_META_NODETYPE_REGISTERY

        :param autofill: 'str' cast all the MayaNode attrs into the class dict by default. 

                Updated: modes: 'all' or 'messageOnly'. all casts every attr, messageOnly 

                fills the node with just message linked attrs (designed for MetaClass work 

                with HIK characterNode)

        

        .. note::

        

            mNode is now a wrap on the MObject so will always be in sync even if the node is renamed/parented

        '''

kind of standard from what I can tell. I'll take a look at the decorator stuff

thanks

To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/CAPGFgA2Vow22SaX9S%3DZ0onRk6d9EyAdBFHxCphR4aW%2B65n39kQ%40mail.gmail.com.

For more options, visit https://groups.google.com/groups/opt_out.

--

[David Moulder]

Are you setting the autodoc flag?

This is how I set it up at Eurocom.

-Dave

To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/CAGQH2FFz3vZDRa_fNvT6eaudaLkAE1VWAF7sviXFO%3DsfvoCbwQ%40mail.gmail.com.

For more options, visit https://groups.google.com/groups/opt_out.

--

David Moulder Technical Animator / Artist squi...@gmail.com Professional Profile	Mobile: +44 (0)7814033242
See who we know in common	Want a signature like this?

[David Moulder]

http://sphinx-doc.org/ext/autodoc.html

[Justin Israel]

Oh, I haven't actually used autosummary before, so I am not sure. 

If you use a directive like this, does it document properly?

.. automodule:: Red9.core.Red9_Meta

    :members:

To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/CABD4PkSRhEgRpWfCx9ZHuHZ50_UA0ufN1FFj_LOHvXcC0E%2BWhw%40mail.gmail.com.

[Mark Jackson]

Hi Dave, yeah I pretty much started with the old Achi doc setup and went from there, just a case of getting my head round the .rst formatting and getting used to how damn picky it is. 

Justin, I'll try that tonight thanks

To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/CAPGFgA1Kzgzz2t2_dUd16e0BdVD6tFGDysuL%3D3LmXm-MqefXFg%40mail.gmail.com.

For more options, visit https://groups.google.com/groups/opt_out.

[Eduardo Grana]

Hey Guys,

May I ask you why did you choose to go with sphinx instead of doxygen?

Cheers!

Eduardo

To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/CAGQH2FHuuD0Yy6n_MPGZR-xz83sOzOs9%3DZU0JDk6e34jHFYyGg%40mail.gmail.com.

For more options, visit https://groups.google.com/groups/opt_out.

--
Eduardo Graña
www.eduardograna.com.ar

[Mark Jackson]

I'm still deciding to be honest, Sphinx was easier to drop into purely because I had good examples. I'm wanting to find a nice tight solution that I can not only use for Red9 but also roll out for the Crytek Maya pipelines, using Red9 as a test bed. Have to say so far I'm finding the formatting from Sphinx a bit clunky but that might just be me & rst formatting.  

To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/CACt6Gr%3DpyCSxM_TR%3DyZ_KJeHoqT9cL9FR9r4DD_XCQyoqMnefQ%40mail.gmail.com.

For more options, visit https://groups.google.com/groups/opt_out.

[David Moulder]

I used Sphinx at eurocom because pymel was done with it, I had examples and I could easily trigger the build from my IDE. At the time was eclipse.  PyCharm has integration with both these days and auto-completes your __doc__ from the method definitions for you. 

Yeah Mark.  The rst markup is a little weird at 1st.  Also the automodule and autodoc features work when they wanted.  But in the whole it was very successful.

To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/CAGQH2FHKdAT2E7G2JBmJwEyq2qeA9CuVFcW1fBhTWBSdgonKTA%40mail.gmail.com.

For more options, visit https://groups.google.com/groups/opt_out.

[Mark Jackson]

Think most of the stuff I didn't like was just the default template by the look of it, spent last night tweaking and it's way better. Still need to get my head round the decorator issue mind you

cheers

Mark

To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/CABD4PkSeQw7YYwE-pC1utMKv1BBjaBXbRSc3X4BkLZJiyvZN%2BA%40mail.gmail.com.

For more options, visit https://groups.google.com/groups/opt_out.

[David Martinez]

This theme is quite neat and similar to the one of readthedocs: https://github.com/armstrong/armstrong_sphinx

You will probably want to change the default colors though.

:-)

--
David Martinez - Technical Animator

 

Email: david.mar...@gmail.com

Website: http://www.elusiveideas.com

To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/CAGQH2FFBWn54SXDUWO7WhH8AjshB1kUmyTc-DuMHxeisuUBfYw%40mail.gmail.com.

[David Moulder]

The decorator issue?

This is not a problem with sphinx but your decorator.  You should use use the @wraps decorator inside your decorator and then you'll propergate the __name__ and __docs__ up the chain to the wrapped function.

quick search...

http://artemrudenko.wordpress.com/2013/04/15/python-why-you-need-to-use-wraps-with-decorators/

-Dave

To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/CAMLeNpzFfF2wj%3Dos36xpFgEtf7u6SLxKnGYCsm6ADPM1-xmmyA%40mail.gmail.com.

For more options, visit https://groups.google.com/groups/opt_out.

[Mark Jackson]

thanks Dave, that fixed it :)

To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/CABD4PkTzt8eD4Rznq25LPtcr50SKfi2PZbO6G51M1o5%2Bd%3DrfVw%40mail.gmail.com.

For more options, visit https://groups.google.com/groups/opt_out.