1

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

mzjn
  • 48,958
  • 13
  • 128
  • 248
Nathan Ward
  • 61
  • 3

1 Answers1

0

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 ?

mverboven
  • 1
  • 1
  • 1
  • This does not really answer the question. If you have a different question, you can ask it by clicking [Ask Question](https://stackoverflow.com/questions/ask). To get notified when this question gets new answers, you can [follow this question](https://meta.stackexchange.com/q/345661). Once you have enough [reputation](https://stackoverflow.com/help/whats-reputation), you can also [add a bounty](https://stackoverflow.com/help/privileges/set-bounties) to draw more attention to this question. - [From Review](/review/late-answers/29912379) – isopach Sep 24 '21 at 15:49
  • Your answer could be improved with additional supporting information. Please [edit] to add further details, such as citations or documentation, so that others can confirm that your answer is correct. You can find more information on how to write good answers [in the help center](/help/how-to-answer). – Community Sep 24 '21 at 20:39
  • @isopach Thanks for your reviewing work here. You are absolutely right that I am not really answering the question here, but it also is not a different question. I ran into exactly the same issue, and just tried to clarify the context, so others have more to go on. Kind regards. – mverboven Sep 27 '21 at 07:49