Working example of auto api generation

[jkingslake]

I am trying to get the workflow described here https://jupyterbook.org/en/stable/advanced/developers.html working but I'm having difficulties.

My main issue is correctly referencing the module from api.rst.

A working example would be really useful if anyone knows of one.

Thanks!

[agoose77]

@jkingslake it would be helpful if you have an example of your current efforts in a Git repository somewhere. Would you be able to share your progress?

[jkingslake]

Hi @agoose77, thanks for the reply.

Here is an example repo that I made that successfully uses autodoc2 to generate the API reference.

And here is the rendered documentation.

I was finding various other problems with the other extensions mentioned on this page autodoc didnt have an option for pointing it to the correct directory (unless I missed it or its undocumented).

Autodoc2 has an option to define autodoc2_packages in the config file (that link refers to config.py, but it worked defining it in the config.yaml instead).

autodoc instead needed me to append the api directory to the python path in the config.py. But I couldnt work out how to do that through a config.yaml.

autoapi failed for another reason, i think, related to how it defined the toc (bottom-up vs top-down?).

For now I am happily using autodoc2, but it was a bit of struggle.

Thanks!

[jkingslake]

p.s. one thing that seemed like a bit of a hack that I would like to get noted down here before I forget is in that repo in api.md line 36.

This line 'includes' an md file generated by autodoc2. It isnt using a special directive supplied by autodoc2 (which seems like the recommended way). It instead just relies on autodoc2 generating apidocs/lumache/lumache.md before we get to the stage of building the book and includes it in api.md with ```{include} apidocs/lumache/lumache.md```

[romanlutz]

If anyone has had success making this work with autodoc2 and Google style docstrings I'm super interested, too. The ones @jkingslake uses seem to be numpydoc style. There's https://github.com/sphinx-extensions2/sphinx-autodoc2/issues/33 which debates this for just sphinx + autodoc2 but with jupyter-book the suggested fixes don't seem to work because the custom parser for autodoc2 isn't picked up (or I'm configuring it in the wrong place, hard to say). If there's any suggested way to debug this I'd love to give it a try because this has been an issue for a while for me.

[fountaindive]

Hi @agoose77, thanks for the reply.

Here is an example repo that I made that successfully uses autodoc2 to generate the API reference.

And here is the rendered documentation.

I was finding various other problems with the other extensions mentioned on this page autodoc didnt have an option for pointing it to the correct directory (unless I missed it or its undocumented).

Autodoc2 has an option to define autodoc2_packages in the config file (that link refers to config.py, but it worked defining it in the config.yaml instead).

autodoc instead needed me to append the api directory to the python path in the config.py. But I couldnt work out how to do that through a config.yaml.

autoapi failed for another reason, i think, related to how it defined the toc (bottom-up vs top-down?).

For now I am happily using autodoc2, but it was a bit of struggle.

Thanks!

Thanks for the pointer to autodoc2 it seems to work alright and it's nice that you can specify the path to the source files.