0

I have a problem when building my documentation with Sphinx autodoc. My project consists of different modules which contain classes. The documentation for these modules is generated correctly.

But there is one module (in my case called controller.py) which contains code to initialize objects from the other modules and to start threads and so on.

Since the module code is executed by Sphinx when building the documentation, I added to my controller.py following to prevent the code from running:

if __name__ == '__main__':
    main()

Further, all the code which is executed is contained in the main function like this:

''' A. general description of controller.py module '''
import mymod1, mymod2, mymod3

    def main():
       ''' B. initializing obj1 '''
       obj1 = mymod1.class1()
       obj2 = mymod2.class2()
       ''' C. doing something '''
       obj2.run()

if __name__ == '__main__':
    main()

The problem is the output of Sphinx for controller.py which only contains the outer main function:

A. general description of controller.py module

controller.main()

What I want to acheive, is to see comment B. and C. too, which is no problem at the other modules because the inner code is contained in a class. But here the code, which is contained in a function, is ignored.

Is there a way to get the result without changing the Python code too much? I want to keep the dependencies between the code and the documentation low.

Any hint is appreciated. Thanks.

EDIT: I switched to apidoc, but the problem is similar. I can see my comments which are in main() but no comments for function definitions inside of main. Example:

def main():
   ''' This comment is visible '''
   def smallfunction():
      ''' This comment is NOT visible '''

Further, it would be great if there would be a possiblitiy to include the source code and not only the API. <- EDIT: This part is solved now. In docs/source/config.py there must be added the entry 'sphinx.ext.viewcode' to extensions to include a link to the source code

A. L
  • 131
  • 2
  • 12
  • It looks like your `main` function has two docstrings (note: not comments). That does not work. Only the first one is recognized. There can be only one docstring per module, class or function. The indentation of the function code looks strange too. – mzjn Jun 14 '18 at 15:21
  • A function defined inside a function is not part of the public API. A user of your code cannot call it directly. Why do you need to document it with Sphinx? Related: https://stackoverflow.com/q/29683426/407651, https://stackoverflow.com/q/18973117/407651 – mzjn Jun 14 '18 at 16:11
  • Regarding includíng source code in the documentation: take a look at http://www.sphinx-doc.org/en/master/ext/viewcode.html – mzjn Jun 14 '18 at 16:12
  • @mzjn Thanks for your reply. The aim of the documentation is to have the implementation details accecible from several projects which use the API (GUI Framework). The main function which determine the behaviour of the GUI differs in each project, the callback functions are defined nested inside of the main function. Like in doxygen, switching to the implementation would be great. So there would be a convenient way to share the information between more developers, how a project was realized and what the idea was. But maybe I have to move the information into thr .rst files – A. L Jun 14 '18 at 16:37

0 Answers0