jamesaleedham / sphinx-autosummary-recursion Goto Github PK

Demonstrating the new automatic package recursion facility in sphinx.ext.autosummary version 3.1

License: MIT License

Python 100.00%

sphinx-autosummary-recursion's Introduction

Sphinx-Autosummary-Recursion

The primary goal of this repo is to demonstrate the new automatic package detection facility for Python API documentation available in Sphinx 3.1+. See this StackOverflow answer for context.

A secondary goal is to showcase the integration of Jupyter Notebooks with Sphinx.

The resulting Sphinx-built HTML doc set is available to view on ReadTheDocs.

Automatically creating API documentation

From Sphinx 3.1, sphinx.ext.autosummary has a :recursive: option that iterates over a Python package automatically, so you no longer have to hard code all your module names, or integrate a 3rd party extension to provide this functionality. Scroll down this Sphinx documentation for more information.

This repo demonstrates how to:

Point Sphinx at the top of a Python source code tree, and have it automatically find all the modules in the package, however deeply nested.
For each module, list the attributes, functions, classes and exceptions in that module in summary tables.
For each entry in a summary table, create a hyperlink to a new page displaying the extracted docstrings for that attribute, function, class or exception.
For each class, document (my choice of) inheritance, public members, inherited members, and special members such as __call__. Other choices are available.

For more information, start with docs/README.

Integrating Jupyter Notebooks with Sphinx

Jupyter Notebooks blend live code, text and visualizations. It’s often useful to integrate them alongside API documentation to provide tutorial-style material.

For more information, start with docs/notebooks/README.

Switching between different HTML themes

Since it’s hosted on Readthedocs, the default theme (stylesheet) for the HTML doc set is sphinx-rtd-theme. There's a small alteration to this theme’s CSS to make the page width slightly wider; see docs/_static/readthedocs-custom.css.

Other themes are available; settings to switch over to the popular pydata-sphinx-theme are commented out in docs/conf.py.

sphinx-autosummary-recursion's People

Contributors

Stargazers

Watchers

sphinx-autosummary-recursion's Issues

Duplicate object warnings.

Hello!
Thank you for this great illustration. I am implementing this approach for my OpenSees_Model_Generator repo, and I noticed that during the process of building I am getting a ton of warnings of the form: "WARNING: duplicate object description of X, other instance in _autosummary/Y, use :noindex: for one of them." Also, "WARNING: document isn't included in any toctree."
I am getting the same warnings when I build the docs from this repo. Is there a way to address those warnings and get a clean build output? This would allow spotting and addressing other warnings which are now kind of hard to locate.
I would really appreciate any help you can provide. Thank you again!

Missing license

Thank you for this very useful example!

Would you mind adding a license? So I can know whether I am allowed to take from it.

Does this work with markdown? Getting lots of warnings

@JamesALeedham, is it expected that the functionality in this repo should still work? I tried to produce my own version for my project with absolute minimum functionality, except using markdown (myst-parser). As far as I can see, I am doing everything exactly equivelant to your example except without templates (starting very simple).

Structure

Here's my repo structure:

bqtemplatemanager/  # this is my package
    __init__.py
    foo.py
    bar.py
docs/
    conf.py
    index.md
    api.md

Files

conf.py

import pathlib
import sys

sys.path.insert(0, str(pathlib.Path(__file__).parents[2]))

project = "bq-template-manager"
release= "1.0"

extensions = [  # noqa: F841
    "myst_parser",
    "sphinx.ext.autodoc",
    "sphinx.ext.autosummary",
    "sphinx.ext.todo",
    "sphinx.ext.viewcode",
    "sphinx_autodoc_typehints",
]

autoclass_content = "both"  # noqa: F841
autosummary_generate = True  # noqa: F841

set_type_checking_flag = True 
source_suffix = {
    ".md": "markdown",
    ".rst": "restructuredtext",
}

index.md

# bq-template-manager

```{toctree}
---
hidden:
---
Home <self>
API Reference <_autosummary/bqtemplatemanager>
```

api.md

# API Reference

```{autosummary}
---
toctree: _autosummary
recursive:
---
bqtemplatemanager
```

Errors

When I build the docs, I see the following warnings in my terminal:

WARNING: html_static_path entry 'static' does not exist
api.md:3: WARNING: autosummary: stub file not found 'bqtemplatemanager'. Check your autosummary_generate setting.
index.md:3: WARNING: toctree contains reference to nonexisting document '_autosummary/bqtemplatemanager'
checking consistency... api.md: WARNING: document isn't included in any toctree

1 - I assume the static warning is irrelevant.
2 - I don't understand what "stub file not found" means.
3 & 4 - I guess these errors follow from the failure of 2

HTML

When I visit the html docs:

the index page is completely void of content and no sidebar navigation or anything
if I visit manually browse to /api.md, I see this a table with just this 1 row in it:

The interesting thing here is that that docstring IS coming from the package docstring (__init__.py) so it looks like something is sort of working clearly not entirely because :obj:bqtemplatemanager <bqtemplatemanager>\ is strange syntax and it's not clickable. I can see that there is no _autosummary folder within my built docs location.

Help!

Error for Windows users when 'make html'

Hi, James
Thanks for the great work!!!
It was my first time to use sphinx-apidoc.
You do help save my time and solve the issues.

In the docs folder,
both sphinx-apidoc -f -o source ..
and sphinx-apidoc -f -o source mytoolbox
works for generating the rst files.

This repo works well on my MacOS system.
But it shows the following error when I switched to a Win system.

Configuration error:
config directory doesn't contain a conf.py file (C: \Users \<MyName>\Desktop\auto_test\docs\source)

To solve this error, in the docs\make.bat,
I changed set SOURCEDIR=source to set SOURCEDIR=.,
the error was fixed.

Hope it works for people who meet the same issue.

arguments / methods / classes are not parsed properly

Hey @JamesALeedham, thanks for this repo which certainly saved me a lot of headaches. Previously I am not able to generate auto-summary for some of my deeper classes and link them to a new page for detailed documentation. However, I still got a few new problems. Hope you may offer me some thoughts:

as you can see from my API page, my current issues are the parts related to classes in Conventional scRNA-seq (est) or Time-resolved metabolic labeling based scRNA-seq (est.tsc).

firstly the docstring doesn't seem to parse correctly and is different from all other function/class while they used the same format: for example: https://dynamo-release.readthedocs.io/en/latest/_autosummary/dynamo.est.csc.ss_estimation.html#module-dynamo.est.csc.ss_estimation
None of the methods, inherited classes, etc. are listed on the linked page.

While other shallower classes are documented correctly, for example:
https://dynamo-release.readthedocs.io/en/latest/_autosummary/dynamo.mv.StreamFuncAnim.html#dynamo.mv.StreamFuncAnim
or
https://dynamo-release.readthedocs.io/en/latest/_autosummary/dynamo.vf.vfGraph.html#dynamo.vf.vfGraph

My doc folder is here: https://github.com/aristoteleo/dynamo-release/tree/master/docs/source
The API page is here: https://dynamo-release.readthedocs.io/en/latest/API.html