Re: Class name manipulation in autodoc
Hi Pauli, I think this idea is promising. I think for now I will take a look at Doug's idea of using a preprocessor, as that might be easier to get started, but this coming weekend I'll dig into this. Looking at the autodoc sources, this could be a relatively easy addition, particularly if it were kept just to the directive, allowing for standard sphinx constructions to generate the markup for the method/function signature. Thanks very much! -Matt On Wed, May 20, 2009 at 4:42 AM, Pauli Virtanen p...@iki.fi wrote: Hi, Tue, 19 May 2009 20:12:38 -0700, Matthew Turk kirjoitti: [clip] identically to how the autodoc extension would work -- rather than autodocing the underlying class itself, which is not meant to be accessed directly. Is there a way to supply an override to the displayed name (in addition to the signature) of an autodoc-processed object? If not, any hints on where to start in adding this functionality? Perhaps Sphinx should grow an `autodocstring` directive, which would insert just the docstring of the item? This should be easy and clean to implement. Then, the documentation could be done using .. class:: foo.Ham(signature) .. autodocstring:: foo.Spam Thoughts? -- Pauli Virtanen --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups sphinx-dev group. To post to this group, send email to sphinx-dev@googlegroups.com To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en -~--~~~~--~~--~--~---
Re: Class name manipulation in autodoc
Matthew Turk schrieb: Hi there, Just as an upfront, I'm loving using sphinx to document a project. I'm writing because I'm stuck at a particular usage pattern we have in our code, and how to properly document it. We have objects that have affiliated derived quantities -- to get at these one usually accesses a dictionary, which then can get called with any number of arguments. For instance, my_object.quantities[MaxLocation](Density) would call the MaxLocation quantity (which is actually an object with a __call__ method) and return the results. What I'd like to do is to supply the class and the method and have it appear in the documentation as: my_object.quantities[MaxLocation] [docstring] identically to how the autodoc extension would work -- rather than autodocing the underlying class itself, which is not meant to be accessed directly. Is there a way to supply an override to the displayed name (in addition to the signature) of an autodoc-processed object? If not, any hints on where to start in adding this functionality? The canonical way to do this would be to add a new Documenter class that knows how to document these quantities. It can then overwrite its add_directive_header method (I just added a format_name method in trunk that makes it even easier) and display the desired format. Georg --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups sphinx-dev group. To post to this group, send email to sphinx-dev@googlegroups.com To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en -~--~~~~--~~--~--~---
Re: Class name manipulation in autodoc
On May 19, 2009, at 11:12 PM, Matthew Turk wrote: Hi there, Just as an upfront, I'm loving using sphinx to document a project. I'm writing because I'm stuck at a particular usage pattern we have in our code, and how to properly document it. We have objects that have affiliated derived quantities -- to get at these one usually accesses a dictionary, which then can get called with any number of arguments. For instance, my_object.quantities[MaxLocation](Density) would call the MaxLocation quantity (which is actually an object with a __call__ method) and return the results. What I'd like to do is to supply the class and the method and have it appear in the documentation as: my_object.quantities[MaxLocation] [docstring] identically to how the autodoc extension would work -- rather than autodocing the underlying class itself, which is not meant to be accessed directly. Is there a way to supply an override to the displayed name (in addition to the signature) of an autodoc-processed object? If not, any hints on where to start in adding this functionality? I've had good luck generating .rst files programmatically based on data structures like that by running a separate program outside of sphinx. For example, we have a large set of system events in our application. I generate the complete table of all event ids with their associated arguments using a little Python script prior to running sphinx-build. Then I either reference the files from a toctree directive or include them (depending on what I'm generating). It's not as fancy as overriding built-in behavior of sphinx, but it's easy to understand and gets the job done. Doug --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups sphinx-dev group. To post to this group, send email to sphinx-dev@googlegroups.com To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en -~--~~~~--~~--~--~---
Re: Class name manipulation in autodoc
Hi, Tue, 19 May 2009 20:12:38 -0700, Matthew Turk kirjoitti: [clip] identically to how the autodoc extension would work -- rather than autodocing the underlying class itself, which is not meant to be accessed directly. Is there a way to supply an override to the displayed name (in addition to the signature) of an autodoc-processed object? If not, any hints on where to start in adding this functionality? Perhaps Sphinx should grow an `autodocstring` directive, which would insert just the docstring of the item? This should be easy and clean to implement. Then, the documentation could be done using .. class:: foo.Ham(signature) .. autodocstring:: foo.Spam Thoughts? -- Pauli Virtanen --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups sphinx-dev group. To post to this group, send email to sphinx-dev@googlegroups.com To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en -~--~~~~--~~--~--~---
