1

Suppose I have a project with the following structure:

mypackage
├── mypackage
│   ├── __init__.py
│   ├── someclass.py
│   └── somefunction.py
└── setup.py

Then I have __init__.py as:

from mypackage.someclass import someclass
from mypackage.somefunction import somefunction

And someclass.py as:

class Someclass:
...

And somefunction.py as:

def somefunction:
...

It's not possible to "hide" mypackage.someclass.Someclass and mypackage.somefunction.somefunction from users so only mypackage.Someclass and mypackage.somefunction are available, right?

But the thing is that Sphinx is actually documentating mypackage.someclass.Someclass and mypackage.somefunction.somefunction instead of mypackage.Someclass and mypackage.somefunction.

And in the case of mypackage.somefunction.somefunction, it's not even accessible if I import mypackage, which is pretty bad.

So, is it possible to have Sphinx document mypackage.Someclass and mypackage.somefunction? According to what I read on other answers this might be done by editing __module__ or using autoclass, but I wasn't able to archieve this right now

random_user
  • 820
  • 1
  • 7
  • 18
  • 1
    This looks similar to http://stackoverflow.com/q/15115514/407651 – mzjn Apr 07 '17 at 07:02
  • 1
    @mzjn yes! I searched a lot for it but don't remember spoting that question, possibly because the title does not contain `sphinx`. The answer worked there fine, and according to https://meta.stackexchange.com/questions/10841/how-should-duplicate-questions-be-handled I will vote this one to close. – random_user Apr 07 '17 at 12:36

1 Answers1

2

Use autoclass as described in the Sphinx documentation sphinx.ext.autodoc – Include documentation from docstrings.

In order for autoclass (and any other autodoc feature) to work, the module must be importable.

autodoc will document the API of your module, and you can add docstrings in reStructuredText format as narrative documentation to explain usage.

It's a good idea to have a docs directory next to your package directory.

mypackage
├── docs
│   ├── conf.py
│   ├── other sphinx stuff
│   └── index.rst
├── mypackage
│   ├── __init__.py
│   ├── someclass.py
│   └── somefunction.py
└── setup.py

Organize your .rst files within docs. Your module is an API, so you could organize your .rst files like so:

mypackage
├── docs
    └── api
        ├── someclass.rst
        └── somefunction.rst

In each of the files in the api directory, use the appropriate syntax.

.. autoclass:: someclass
.. autofunction:: somefunction

There's also several options covered in the aforementioned Sphinx documentation.

Steve Piercy
  • 13,693
  • 1
  • 44
  • 57
  • Thanks. My question was more directed at `sphinx-apidoc`, sorry I didn't mentioned it, but anyway, I kinda give up on it (`sphinx-apidoc`) and started doing it manually. – random_user Apr 06 '17 at 21:32
  • [sphinx-apidoc relies upon autodoc](http://www.sphinx-doc.org/en/stable/man/sphinx-apidoc.html). If you put forth what you tried, expected, and observed with `sphinx-apidoc`, then I might be able to guide you forward. – Steve Piercy Apr 07 '17 at 05:55
  • Do not worry, the question is actually duplicated, but thank you very much for your answer and being helpful. – random_user Apr 07 '17 at 12:38