Newbie question about Autodoc

[DavidA]

Hi

I am new to Sphinx. I want to use it to document my Python project. Working on Windows, I have installed Sphinx, including the Autodoc extension.  I have run sphinx-quickstart to create a project.

Now, supposing I have a Python script called main.py, what directives should I use to pull the docstrings out of main.py, and where should I put those directives?

Best regards

David

[Takayuki Shimizukawa]

Hi David,

You should use::

  .. automodule:: main

     :members:

I hope my EuroPython presentation slide would help you.

http://www.slideshare.net/shimizukawa/sphinx-autodoc-automated-api-documentation-europython-2015-in-bilbao

Regards,

--

Takayuki SHIMIZUKAWA

http://about.me/shimizukawa

--
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...@googlegroups.com.
To post to this group, send email to sphinx...@googlegroups.com.
Visit this group at http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.

[DavidA]

Hi Takayuki 

Thanks for your answer. Where exactly do I put '.. automodule:: main' ?

Regards

David

[Werner]

Hi David,

On 7/30/2015 13:57, DavidA wrote:
> Hi Takayuki
>
> Thanks for your answer. Where exactly do I put '.. automodule:: main' ?

See e.g. slide 27 of Takayuki's slide show in the link he gave you.

Here is another tutorial which might help.

https://codeandchaos.wordpress.com/2012/07/30/sphinx-autodoc-tutorial-for-dummies/

Werner

[Werner]

Hi David,

Better keep things on the list, as it might help others.

On 7/30/2015 18:34, David Aldrich wrote:
>> I think you need to add the following at the top of your file.
>>
>> .. module:: main
> Hi Werner
> Thanks. That works better. But I do run into problems if the source file
> is importing modules from unusual paths. I am working with Kivy and see:
> C:\PythonDocs\index.rst:19: WARNING: autodoc: failed to import class
> 'CSchematic' from module 'main'; the following exception ...
> Traceback (most recent call last):
> File
> "C:\Kivy-1.9.0-py3.4-win32-x64\Python34\lib\site-packages\sphinx\ext\autodoc.py",
> line 385, in import_object
> __import__(self.modname)
> File "C:\SVNProj\Raggio\trunk\hostconsole\gui\main.py", line 56, in
> <module>
> import mygraph
> File "C:\SVNProj\Raggio\trunk\hostconsole\gui\mygraph.py", line 23,
> in <module>
> from kivy.garden.graph import Plot, Graph, MeshLinePlot,
> MeshStemPlot, LinePlot
> File "<frozen importlib._bootstrap>", line 2237, in _find_and_load
> File "<frozen importlib._bootstrap>", line 2226, in
> _find_and_load_unlocked
> File "<frozen importlib._bootstrap>", line 1191, in _load_unlocked
> File "<frozen importlib._bootstrap>", line 1163, in
> _load_backward_compatible
> KeyError: 'kivy.garden.graph'
> I wonder if I can just get Sphinx to ignore 'kivy.garden.graph'. Do you
> have a suggestion for how best to fix this please?
Sorry not sure what is the best way to do this.

Is 'kivy' installed on your system? If not I would install it, as it
should be there as Sphinx does an 'import' of your module, but by
default it will not document it - see "inherited-members" in the
autoclass directive -
http://sphinx-doc.org/ext/autodoc.html?highlight=autoclass#directive-autoclass

Also I am bit confused as you get a KeyError, so really not sure what
causes this.

Werner

[DavidA]

Thanks for your replies.  I have got a little further now - Sphinx is finding my source files. However, I'm not yet getting the results I want.

I have chosen not to use sphinx-apidoc because, when I run make against its output files, I get reports of various modules that can't be found. So I've chosen to specify the classes I want to document explicitly.

I have a main.py source file that contains a class called 'CSchematic'.

In index.rst I specified:

.. automodule:: main

.. autoclass:: CSchematic

    :members:

but 'make html' reports:

C:\index.rst:16: WARNING: don't know which module to import for autodocumenting 'CSchematic' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)

Please can you suggest what is wrong with my directives?

Best regards

David

[DavidA]

When I run 'make html' I get an import error for my source file:

ImportError: No module named 'pathimport'

I am not interested in that module.  Must all modules resolve in order for the process to work?

If so, what is the easiest way of setting the search path?

Best regards

David