0

I want to use, let's say, .. autoclass:: Foo in my docstring, but as a result, I want to obtain only Foos docstring, not the name + signature + docstring. I tried to use .. autodata:: etc., but the result didn't change - it always results with at least class name.

class Foo:
"""
foo docs
"""
    ...


class Bar:
"""
bar bar bar

.. autodata:: Foo
    :annotation:

restaurant restaurant
"""
    ...

results in:

bar bar bar
Foo(signature)
foo docs
restaurant restaurant

but I need:

bar bar bar
foo docs
restaurant restaurant

How can obtain desired, described above output? Can I use another docstring in the Sphinx?

mzjn
  • 48,958
  • 13
  • 128
  • 248
Jacek Karolczak
  • 38
  • 5
  • What you're asking for here is very complicated, your approach is wrong to begin with. You aren't supposed to be using autodoc directives inside of docstrings (in other words, inside the `.py` files), the autodoc directives are supposed to be used in the `.rst` files. What's worst, you are nesting autodoc directives, when you apply `.. autodoc:: Bar` later you're expecting the nested `.. autodata:: Foo` to resolve magically (and `Foo` is a class so you shouldn't apply `.. autodata::`) to begin with. – bad_coder Nov 23 '22 at 15:21
  • Yet another difficult and independent task would be to extract the docstring, and insert it, without any other elements. That would have to be done using [Docstring preprocessing](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#docstring-preprocessing). Besides, your question doesn't include any example `.rst` files, so it doesn't have an [MRE](https://stackoverflow.com/help/minimal-reproducible-example)... You need to rethink what you're aiming to do because autodoc isn't meant to be used like that. – bad_coder Nov 23 '22 at 15:25
  • My original idea was to copy doc from `Foo` to `Bar` (`Bar.__doc__ = Foo.__doc__ + "sth"). However using this, sphinx didn't format any parameters etc. Thus I decided to give a shot to sphinx method. – Jacek Karolczak Nov 24 '22 at 07:21
  • Copying the `__doc__` around is usually a workaround, something you avoid using unless you have strong reason to. See this post for [a good file structure](https://stackoverflow.com/a/60159862). The point of the `.rst` files is that they work as a presentation layer, so you should be organizing the layout there [here's a good example](https://stackoverflow.com/a/60094069) that is close to what you want. Just document parameters and maybe attributes in the docstring and afterwards organize the directives in the `.rst`, following that logic things should be easy. – bad_coder Nov 24 '22 at 12:35
  • Consider this on [docstring sections](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#docstring-sections) and see the examples. – bad_coder Nov 24 '22 at 12:35

0 Answers0