:toctree:

[Louis King]

Newbe question. I can't add any files to the toctree.

Using a windows system. Installes Sphinx no problem.

I created a directory on a D: drive

changed to the new directory

used sphinx-quickstart  to build structure

used make html to generate an empty ooutput

copy a file wabbitFB.py to the new directory

add wabbitFB to the index.rst

.. toctree::
   :maxdepth: 2

   wabbitFB
 

Running make html again results in a warning:

D:\tstsphinx\index.rst:9: WARNING: toctree contains reference to nonexisting document 'wabbitFB'

What am I missing?? This has got to be dumb simple, but I don't see it.

[Matthias Geier]

The "toctree" directive can only contain Sphinx source files.

By default, Sphinx only supports reStructuredText files (with the
suffix .rst), but support for other source files can be added with
extensions.

You are trying to use a Python file (with the suffix .py).

If you want to show the contents of this file in your documentation,
you should create a .rst file and in that you can use the
"literalinclude" directive
(https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-literalinclude).

If you want to show the documentation of the functions and classes
that are defined in your Python file, you can try the "autodoc"
extension (https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html).

Or is it something else you want to use your .py file for?

cheers,
Matthias

[Louis King]

Well that explains a lot! I missed that in my rush to see output. At first glance the 'autodoc' looks like what I am looking for. I want something a bit better than pydoc. Thanks Matthias.  Slow down and when all else fails Read The *ing Manual.

Lou

[Louis King]

We are making progress(?)

Added the autodoc extention

added the py source_suffix

and now stuck on adding the source parser for 'py'

I can't seem to get past "Source parser for python not registered"

Can't seem to find my way through this rabbit warren.

[Louis King]

forgot. yes I did add to the index.rst
.. automodule:: wabbitFB
   :members:

[Matthias Geier]

On Tue, May 11, 2021 at 9:34 PM Louis King wrote:
>
> forgot. yes I did add to the index.rst
> .. automodule:: wabbitFB
> :members:

OK, that looks good.

> Added the autodoc extention

OK, good.

> added the py source_suffix

You probably don't want to use .py file as Sphinx sources.

I mean there are use cases for that, but I guess that's not what you
currently want?

>> and now stuck on adding the source parser for 'py'

Don't.

>> I can't seem to get past "Source parser for python not registered"
>>
>> Can't seem to find my way through this rabbit warren.

What is happening now with your "automodule" directive?

Is there some error message or warning?

I guess you may have to tell Sphinx (and the autodoc extension) where
your .py file(s) can be found.

If your wabbitFB.py file is in the same directory as conf.py, you can
try to add this to your conf.py:

import os
import sys
sys.path.insert(0, os.path.abspath('.'))

cheers,
Matthias

[Louis King]

Matthias thanks You got me there! Well close enough I now have output. And with output I know how much I have to learn.

First big set of warnings I got was about docstrings - in a library from the supplier of a custom board I am using.

thanks again for helping a newbie.

Lou