Does this work with markdown? Getting lots of warnings

[adamcunnington-gdt]

@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!

[JamesALeedham]

HI, i've not tried anything to do with markdown, so can't tell whether that's throwing a spanner in the works.

Sphinx is fairly temperamental; it doesn't take much to throw it off balance.

If you send me a link to your repo, I might be able to pull it this weekend and see if I can get anywhere with it...

[adamcunnington-gdt]

@JamesALeedham thanks so much, I'd appreciate that enormously.

https://gitlab.com/medialabgroup/apollo/bq-template-manager

[adamcunnington]

@JamesALeedham did you get chance to take a look at all? thanks again

[JamesALeedham]

Hi Adam, I did have a quick go but unfort. didn't get very far.

Pulled your repo and ran make html in the docs directrory - this fails as there's no Makefile (don't know if this is deliberate)?

Replaced your docs directory with my one from this repo verbatim to see if that would work. This fails with a bunch of errors around failing to import each of the modules. I suspect this is because I haven't installed your package, and I don't have time to go down the private PyPi personal access token route right now - sorry.

I wonder if it's not the Markdown that's the problem, but rather something to do with failing import statements? Perhaps you could replace your docs folder with my one and change instances of mytoolbox to bqtemplatemanager in index.rst and api.rst. Run make html, and if you get some successful output then all is well with imports, and Markdown might be the problem. If you don't get any output, then it might be something more profound to do with imports...

[adamcunnington-mlg]

@JamesALeedham thanks for taking a look - I took a deeper look tonight and it is indeed incompatible with md. Sigh, Sphinx-provided extensions aren't well made and their documentation is even worse. Looks like autosummary only works with rst.

I switched to rst and it's working (with your custom templates).