Dear Matthias, thank you for your tips.
Let me ask the general question. Why do I have to name explicit a module, function, method or member? When using a tool like Sphinx I would assume that the tool scan all my code (all py-files) and create the html-doc out of it depending on the doc-strings. Automatic! The Sphinx configuration feels to heavy at this point. On 2018-09-25 09:09 Matthias Geier <matthias.ge...@gmail.com> wrote: > Welcome to Python and Sphinx! > > Your project setup looks good, there is only one thing where I see a > potential problem (but I'm not sure): > > You did include the option "napoleon_include_private_with_doc", but > the function you are showing (_SetupLogging) is not a member function > (i.e. it is not part of a class). > The documentation just speaks of "member functions": > http://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#confval-napoleon_include_private_with_doc > > You may have to specify your "private" function explicitly: > > .. autofunction:: _SetupLogging > > But as I said, I'm not sure about this. > > In order for other people here to reproduce your problem, it is > typically easier if you provide a very minimal but fully working > example. > In your case you would only need one .py file (with only one > function). You could include the "automodule" stuff directly in > index.rst, not needing any more .rst file. > And then you need a working conf.py, which you also should strip down > to the bare minimum (that still works as it is). > And you should specify in which directories the files are, as you > already did. > > You can include all this in the message (it's only a few lines per > file), people can quickly copy this to some files and try it out for > themselves. > > You could also share your test project online, e.g. on a Github Gist > or something similar, and provide just a link here. > > But most importantly, oftentimes when you create a minimal version of > your problem, you'll find the solution by yourself before even sharing > it! > > cheers, > Matthias > On Tue, Sep 25, 2018 at 12:55 AM <c.bu...@posteo.jp> wrote: > > > > I have problems starting with Sphinx on my Python3 code. > > I read some tutorials and think I understand it. I also looked in > > some example code on GitHub (project: backintime). > > > > But in the result I see only the name of the main module, not more. > > I use sphinx and python3.6 on Debian unstable. > > > > Because I saw it in an example I name the main module explicite. But > > what I would expect is that Sphinx looking in each py-file by > > itself. > > > > This is the folder and structure with some (not all) files > > > > . > > ├── doc > > │ ├── build > > │ │ ├── doctrees > > │ │ │ ├── environment.pickle > > │ │ │ ├── feedybus.doctree > > │ │ │ ├── index.doctree > > │ │ │ └── modules.doctree > > │ │ └── html > > │ │ ├── feedybus.html > > │ │ ├── genindex.html > > │ │ ├── index.html > > │ │ ├── modules.html > > │ │ ├── objects.inv > > │ │ ├── py-modindex.html > > │ │ ├── search.html > > │ │ ├── searchindex.js > > │ │ ├── _sources > > │ │ │ ├── feedybus.rst.txt > > │ │ │ ├── index.rst.txt > > │ │ │ └── modules.rst.txt > > │ │ └── _static > > │ │ ├── ajax-loader.gif > > │ │ ├── alabaster.css > > │ │ ├── basic.css > > │ │ ├── comment-bright.png > > │ │ ├── comment-close.png > > │ │ ├── comment.png > > │ │ ├── custom.css > > │ │ ├── doctools.js > > │ │ ├── documentation_options.js > > │ │ ├── down.png > > │ │ ├── down-pressed.png > > │ │ ├── file.png > > │ │ ├── jquery.js > > │ │ ├── minus.png > > │ │ ├── plus.png > > │ │ ├── pygments.css > > │ │ ├── searchtools.js > > │ │ ├── underscore.js > > │ │ ├── up.png > > │ │ ├── up-pressed.png > > │ │ └── websupport.js > > │ ├── Makefile > > │ └── source > > │ ├── conf.py > > │ ├── feedybus.rst > > │ ├── index.rst > > │ ├── modules.rst > > │ ├── _static > > │ └── _templates > > ├── feedybus > > │ ├── application.py > > │ ├── basics.py > > │ ├── config.py > > │ ├── data.py > > │ ├── entrieslistview.py > > │ ├── fetchfeeds.py > > │ ├── graphic > > │ │ ├── bullet.svg > > │ │ ├── checked.png > > │ │ ├── exit.png > > │ │ ├── ...etc... > > │ ├── __init__.py > > │ ├── __main__.py > > │ ├── make.bat > > │ ├── Makefile > > │ ├── treeview.py > > │ └── window.py > > ├── Feedybus.sh > > > > This are IMO the relevant lines from conf.py > > > > import os > > import sys > > sys.path.insert(0, os.path.abspath('../..')) > > # ... > > extensions = [ > > 'sphinx.ext.autodoc', > > 'sphinx.ext.napoleon', > > 'sphinx.ext.intersphinx', > > 'sphinx.ext.viewcode', > > ] > > # ... > > napoleon_include_private_with_doc = True > > > > The index.rst is untouched by me. > > But modules.rst and feedybus.rst > > > > $ cat doc/source/modules.rst > > common > > ====== > > > > .. toctree:: > > :maxdepth: 4 > > > > feedybus > > > > $ cat doc/source/feedybus.rst > > Feedybus > > ======== > > > > .. automodule:: feedybus > > :members: > > :undoc-members: > > :show-inheritance: > > > > The file feedybus/__init__.py is empty. > > The file feedybus/__main__.py as functions with docstrings like this > > > > def _SetupLogging(size, n, debug): > > """Setup the logging mechanism and return the logger object. > > > > Args: > > size (int): Maximum size of a log file in KiloBytes. > > n (int): Maximum number of log files keeped. > > debug (bool): Debug-Level on or off > > > > Returns: > > logging.Logger: > > """ > > > > -- > > You received this message because you are subscribed to the Google > > Groups "sphinx-users" group. To unsubscribe from this group and > > stop receiving emails from it, send an email to > > sphinx-users+unsubscr...@googlegroups.com. To post to this group, > > send email to sphinx-users@googlegroups.com. Visit this group at > > https://groups.google.com/group/sphinx-users. For more options, > > visit https://groups.google.com/d/optout. > -- You received this message because you are subscribed to the Google Groups "sphinx-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users+unsubscr...@googlegroups.com. To post to this group, send email to sphinx-users@googlegroups.com. Visit this group at https://groups.google.com/group/sphinx-users. For more options, visit https://groups.google.com/d/optout.
