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
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 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',
> >
