CODEWITHSUNDEEP
pythonpython-sphinxnamespace-packagesphinx-apidoc
Nathan Ward
Nathan Ward

Reputation: 71

Namespaces packages several levels deep, and sphinx

I'm trying to use packages like "project-a" in a namespace like "com.company", with implicit namespaces.

I'm finding that sphinx-apidoc isn't putting my packages in to the toc in the docs, I suspect because both the com and company namespaces have nothing in them.

sphinx-apidoc is running with --implicit-namespaces, from the standard config pyscaffold gives me in a basic project.

I get the following in my sphinx-build output:

checking consistency... /Users/nward/Code/scratch/namespaces/project-a/docs/api/com.company.rst: WARNING: document isn't included in any toctree

Any ideas, before I start digging in to the sphinx code?

I've posted the code here - really nothing to it at the moment: https://github.com/nward/com_company_project-a

Upvotes: 1

Views: 1263

Answers (1)

mverboven
mverboven

Reputation: 1

I am running into the same issue trying to convert a python package to native namespaces.

I have been running tests trying to solve this using the native folder from https://github.com/pypa/sample-namespace-packages as per documentation https://packaging.python.org/namespace_packages but with an extra level like:

setup.py
docs/
example_pkg/
    # No __init__.py here.
    middle_package/
        # No __init__.py here.
        subpackage_a/
            # Sub-packages have __init__.py.
            __init__.py
            module.py

the commands to generate the documentation are, first:

sphinx-apidoc --implicit-namespaces --force -o docs/ ./example_pkg/

then

make -C docs html

The problem seems to be that the example_pkg.rst does not contain any link to a subpage which is expected:

example\_pkg namespace
======================

.. py:module:: example_pkg

instead of:

example\_pkg namespace
======================

.. py:module:: example_pkg

Subpackages
-----------

.. toctree::
   :maxdepth: 4

    example_pkg.subpackage_a

When using pkgutil-style namespace packages everything does work as a charm though ?

Upvotes: 0

Related Questions