Re: [sphinx-users] First steps with Pyhton and Sphinx
I am sorry, but the html pages are still empty. I only see the project name but no sub modules, methodes, functions or something else. This is the output while make $ make html Sphinx v1.8.1 in Verwendung Lade pickle Umgebung...erledigt [autosummary] generating autosummary for: index.rst building [mo]: targets for 0 po files that are out of date building [html]: targets for 0 source files that are out of date updating environment: [] 0 added, 1 changed, 0 removed reading sources... [100%] index looking for now-outdated files... none found pickling environment... erledigt checking consistency... erledigt preparing documents... erledigt writing output... [100%] index generating indices... genindex py-modindex writing additional pages... search copying static files... done copying extra files... erledigt dumping search index in English (code: en) ... erledigt dumping object inventory... erledigt build abgeschlossen. 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
Your project was almost perfect, there was only one detail missing: in every `__init___.py` you must explicitly tell autosummary which subpackages you want to include. See my diff below. HTH Luc $ git diff diff --git a/buhtzsphinx/__init__.py b/buhtzsphinx/__init__.py index 76a9a4a..77157f5 100644 --- a/buhtzsphinx/__init__.py +++ b/buhtzsphinx/__init__.py @@ -2,6 +2,12 @@ This is buhtzsphinx brief line. More complex. + +.. autosummary:: + :toctree: + + mycode + """ from .mycode import * On 04.10.2018 23:59, c.bu...@posteo.jp wrote: > Dear Luc, > > thanks for your explanations. > > I updated my code and pushed it to upstream. > > But it still not working here. Can you give it a try with my code? > . > -- 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
Dear Luc, thanks for your explanations. I updated my code and pushed it to upstream. But it still not working here. Can you give it a try with my code? -- 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
Yes, atelier simplifies my life but for you it makes things more
difficult to understand...
I guess that you should have a look at the
atelier.sphinxconf.configure() function:
https://github.com/lino-framework/atelier/blob/master/atelier/sphinxconf/__init__.py#L64
configure() updates the globals() namespace of the conf.py file, so when
it does
*globals_dict.update(foo='bar')* then that's as if you would type
*foo='bar'* in your conf.py file.
Quick translated excerpt of autosummary options that might be relevant
for you:
autodoc_default_options={ 'members': None, 'show-inheritance': None}
autodoc_member_order='bysource'
autodoc_inherit_docstrings=False
HTH
Luc
On 03.10.2018 14:44, c.bu...@posteo.jp wrote:
> Dear Luc,
>
> thank you for this valuable hint. Your example doc looks awesome and
> exactly as this what was in my mind.
>
> The test with my own code did not work.
> https://gitlab.com/buhtz/buhtz-sphinx
> I always do a "make html" in the doc-directory to generate the doc.
>
> But I have not copied your conf.py exactly.
> https://gitlab.com/buhtz/buhtz-sphinx/blob/master/doc/source/conf.py
> Because I didn't understand all details of your conf.py. What is this
> with the "import atelier" in it? Why do you use the package that should
> be documented in your conf.py file?
> You also use a lot more atelier calls in the conf.py file.
>
> It would help my understanding to see a minimal example.
>
> The sphinx-doc website about autosummary doesn't explain how to
> configure a complete project environment to run.
> .
>
--
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
Dear Luc, thank you for this valuable hint. Your example doc looks awesome and exactly as this what was in my mind. The test with my own code did not work. https://gitlab.com/buhtz/buhtz-sphinx I always do a "make html" in the doc-directory to generate the doc. But I have not copied your conf.py exactly. https://gitlab.com/buhtz/buhtz-sphinx/blob/master/doc/source/conf.py Because I didn't understand all details of your conf.py. What is this with the "import atelier" in it? Why do you use the package that should be documented in your conf.py file? You also use a lot more atelier calls in the conf.py file. It would help my understanding to see a minimal example. The sphinx-doc website about autosummary doesn't explain how to configure a complete project environment to run. -- 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
I also found the autoapi extension. But even this is far away from being "auto" because I have to write all members into the __all__ variable in each module. The point for me in "auto" is I don'T want to think about if I have to add a new created member to an __all__ variable or write it into an rst-file or whatever. Isn't there nothing out there doing this automatic? It is just py-file parsing and then rearrange the data to a html (or whatever) file. I don't see how sphinx and Co can improve my workflow and save my time resources. I am sure there is an advantage of Sphinx because the whole world is using it. But I am not seeing it. So please help the blind. ;) On 2018-09-28 21:40 Matthias Geier wrote: > On Thu, Sep 27, 2018 at 4:09 PM c.buhtz wrote: > > > > Dear Matthias, > > > > I fixed the module name and added a autodoc command to the rst file > > - see in upstream. > > > > The result is the same. The "module index" in the docs is empty. > > OK, we are getting closer. > > The first little thing is a missing space. You wrote: > > .. automodule::buhtzsphinx > > but it should be: > > .. automodule:: buhtzsphinx > > But it still doesn't work ... > > The next problem is that what you wrote into __main__.py should > actually go into __init__.py. > > If you do that, you'll get something! Congratulations! > > But the docs for myclass.MyClass are still missing ... > > It turns out that I was wrong in thinking that "automodule" would > automatically include submodules. It looks like it doesn't. You'll > have to specify each module separately, e.g.: > > .. automodule:: buhtzsphinx.myclass > :members: > > This should finally show the docs of MyClass! > > cheers, > Matthias > -- 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
Dear Matthias, I fixed the module name and added a autodoc command to the rst file - see in upstream. The result is the same. The "module index" in the docs is empty. -- 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
On Thu, Sep 27, 2018 at 12:17 AM c.buhtz wrote: > 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 Thanks, that makes it much easier to help you! > 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. Sure, you'll have to put *something* into the .rst file. Also, "buhtz-sphinx" is an invalid name for a Python module. To use your module you would have to do: import buhtz-sphinx ... but that's a syntax error in Python (just try it, you'll see). Once you fix those issues, we can probably get closer to the solution ... cheers, Matthias > 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
Dear Matthias, thanks for your message. Am 26.09.2018 18:19 schrieb Matthias Geier: 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. You describe here two different scenarios: Opt-In and Opt-Out. Both of them make sense for some users and/or some projects. But it should be up to the user to decide to use an Opt-In or Opt-Out mechanism. Opt-In makes absolutly no sense to me, because this is againts the "automatic" thing I would expect. The current default behavoir of Sphinx makes no sense because the result is empty. Also a complex software like Sphinx should work out of the box, what means producing some docu in a default way. But the idea is that mentioning the module should be enough, as you did: .. automodule:: feedybus :members: I will try this. -- 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
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
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 > > > │ │
Re: [sphinx-users] First steps with Pyhton and Sphinx
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',
> >
