Running sphinx-apidoc equivalent

[cvauclair]

Hi! Currently playing around with mudkip with the hope of using the tool for documenting my projects going forward.

I was wondering how to invoke the autodoc extension using mudkip. In my current sphinx setup, I run the sphinx-apidoc command, which automatically generates the .rst files for my modules and I would like to recover this behavior with mudkip.

I tried running sphinx-apidoc separately before mudkip develop, but then I get some import errors (those are fixed in my current setup by modifying the sys.path variable in conf.py).

Thanks!

[vberlier]

I don't think you should have to modify sys.path for the files generated by sphinx-apidoc to work. autodoc requires your local package to be properly installed to import it and emit documentation. I use poetry to manage my local vitualenv and I didn't have any issue.

[cvauclair]

Hi thanks for the tip! Switching from pipenv to poetry seems to have solved my issue.

It seems that for other venv managers (like pipenv) some extra configuration is required to get mudkip + autodoc working.

[cvauclair]

As a sidenote, any recommendations on how to get mudkip based docs deployed correctly on readthedocs.org? It seems that the platform requires a conf.py file to build properly

[vberlier]

Yeah pipenv manages your virtualenv but I think you still need to set up your package whereas poetry is fully package-oriented and manages the virtualenv as part of setting up everything for developing, building and publishing the package.

Also readthedocs.org does require a conf.py so it's not currently supported. For most projects GitHub Pages should be a lot easier to set up anyway. Just run mudkip build --update-gh-pages.

[epogrebnyak]

As a rough idea maybe allow a command like (similar to original sphinx-apidoc syntax):

poetry mudkip apidoc <MODULE_PATH> [-o | --output-dir OUTPUT_PATH] [--exclude PATTERN]

Also when running mudkip init maybe it can

1. add a proper link to README.md in documentation
2. run apidoc
3. make index.rst with some toctree

That would be a very cool way develop drop-in documentation for Python projects, maybe even for mudkip itself.

[epogrebnyak]

Here is a discusssion of similar usecase https://stackoverflow.com/questions/29385564/customize-templates-for-sphinx-apidoc/42739816.

I second impression that modules/submodules of sphinx-apidoc is a bit too complex, usualli takes time to edit and remeber in frustartion which is a better way.

I like the idea (but not an implementation) of https://github.com/goerz/better-apidoc

[epogrebnyak]

For me personally an ideal behaviour if mudkip init --apidoc <MODULE> creates api.rst in toctree and puts docstring of of .init.py right in api.rst forllowed by API autodocs.

Drop in behaviour for apis best seen I think in https://github.com/pdoc3/ great if mudkip can replicate of surpass that in easiness.

Goog looking API section: https://pandas.pydata.org/pandas-docs/stable/reference/index.html#