Support templating

[gsemet]

Hello

Is it possible to add an option to change the default menu item names:

• the first level has the name of the module while I'd like to have something like "API Reference". Could be an option such as apidoc_title = "API Reference"
• is it possible to display the content of a module before its sub-modules?
• using a lot git submodules, seeing "Submodules" in the menu is weird. Is it possible to simply skip this level and gather all sub-module inside the package?

So instead of:

mypackage_name
    mypackage_name package
        Submodules
            mypackage_name.one_module module
            mypackage_name.another_module module
            mypackage_name.yet_another_one module
        Module contents

We would have something like:

API Reference
    mypackage_name package
        Module contents
        mypackage_name.one_module module
        mypackage_name.another_module module
        mypackage_name.yet_another_one module

[stephenfin]

This is not currently possible as the original Sphinx application that this extension utilizes, sphinx-apidoc, does not support templates or the likes. If we wanted to support this feature, we'd need to essentially vendor and rewrite that application or modify the application upstream so that we would get support for free with the next version of Sphinx. I'd be happy to help produce a PRs for either approach but it's not important enough for me to do solo.

[gsemet]

Ok, I dig into it to see what can be done

• module first is an option of sphinx apidoc: --module-first
• the toc file can be skiped and manually recreated, that pretty much do the job.

So for the moment, sadly, I have disabled sphinx-contrib/apidoc and added this in my general makefile:

DOCS_EXCLUSION=$(foreach m, $(MODULES), $m/tests)

docs: clean-docs sdist docs-generate-apidoc docs-run-sphinx

docs-generate-apidoc:
	pipenv run sphinx-apidoc \
		--force \
		--separate \
		--module-first \
		--doc-project "API Reference" \
		-o docs/source/reference \
		$(PACKAGE_NAME) \
			$(DOCS_EXCLUSION)

docs-run-sphinx:
	pipenv run make -C docs/ html

clean-docs:
	rm -rf docs/_build docs/source/reference/*.rst

docs-open:
	xdg-open docs/_build/html/index.html

I'll see if I have time to exposes this in sphinxcontrib-apidoc in the future. Thanks for this package anyway!

[paulmelnikow]

Is the solution to provide additional additional arguments to sphinx-apidoc? As far as I can tell --doc-project is ignored unless you use --full. However #9 adds an apidoc_module_first option and lets you specify whichever additional arguments you'd like.

[stephenfin]

Is the solution to provide additional additional arguments to sphinx-apidoc? As far as I can tell --doc-project is ignored unless you use --full. However #9 adds an apidoc_module_first option and lets you specify whichever additional arguments you'd like.

Indeed, that's what I'd take out of this. @gsemet Thoughts?

[gsemet]

seems great! thanks will try it asap