Re: [sphinx-users] First steps with Pyhton and Sphinx

[c.buhtz]

On 2018-09-25 09:09 Matthias Geier  wrote:
> In order for other people here to reproduce your problem, it is
> typically easier if you provide a very minimal but fully working
> example.

Please see this MWE.
https://gitlab.com/buhtz/buhtz-sphinx

I didn't modify the rst file.

I would expect that sphinx find all functions, methodes, classes etc by
itself. But the html file is empty.

That is sphinx build run

$ make html
Running Sphinx v1.7.9
making output directory...
loading pickled environment... not yet created
loading intersphinx inventory from
https://docs.python.org/objects.inv... intersphinx inventory has moved:
https://docs.python.org/objects.inv ->
https://docs.python.org/3/objects.inv building [mo]: targets for 0 po
files that are out of date building [html]: targets for 1 source files
that are out of date updating environment: 1 added, 0 changed, 0
removed reading sources... [100%] index looking for now-outdated
files... none found pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%]
index generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.

The HTML pages are in build/html.

-- 
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.

Re: [sphinx-users] First steps with Pyhton and Sphinx

[Matthias Geier]

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
>  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
> > > │   │   

[sphinx-users] Meaning of check_keywords and area

[mlautman]

Sphinx's default search box is an HTML form that passes two hidden fields: 
check_keywords=yes and area=default (listing 

). How are these fields used and what other values can they take?

-- 
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.