On Tue, Sep 25, 2018 at 11:57 PM c.buhtz wrote:
>
> 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?
Well I'm not involved in the development of sphinx.ext.autodoc, so I
don't know the real answer to this.
But I think it makes sense to manually select which modules you want
to be scanned for your documentation. You might have some internal
modules which you don't want to appear in the docs, for example.
But more importantly, you have to tell Sphinx where it should include
the "autodoc" documentation.
You might also want to have your documentation in several parts with
some text in between, or on several pages. All this cannot be
determined automatically.
But the idea is that mentioning the module should be enough, as you did:
.. automodule:: feedybus
:members:
All sub-modules and functions within this module should be found automatically.
We still have to find out why it didn't work in your case.
> 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!
Yes, but where should Sphinx put the documentation?
In the beginning? In the end? Somewhere in between?
One page per module? One page per class? One page per function?
You have to provide *some* information ...
> The Sphinx configuration feels to heavy at this point.
I agree that the configuration can feel overwhelming, but that's
mostly because there is so much to customize!
But you can always ask here when you get stuck!
cheers,
Matthias
> 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.
--
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.
