4

I am currently working on documenting some code, and keep on getting the following warning/error (this is one example of multiple):

WARNING: invalid signature for automodule ('components.component-1.orc_component_1.app) WARNING: don't know which module to import for autodocumenting 'components.component-1.orc_component_1.app' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)

I have tried changing the dots "." with forwarding slashes "/" in the file that sets the paths to the components without any luck.

Below I have sketched out a simplified representation of the project and how I have built the sphinx documentation:

.
|-- README.rst
|-- components
|   |-- component-1
|   |   |-- README.rst
|   |   |-- orc_component_1
|   |   |   |-- app.py
|   |   |   |-- services.py
|   |   |   `-- utils.py
|   |-- component-2
|   |   |-- README.rst
|   |   |-- orc_component_2
|   |   |   |-- app.py
|   |   |   |-- services.py
|   |   |   `-- utils.py
|-- docs
|   |-- Makefile
|   |-- build
|   |   |-- doctrees
|   |   `-- html
|   |-- make.bat
|   `-- source
|       |-- _static
|       |-- _templates
|       |-- components.rst
|       |-- conf.py
|       |-- index.rst
|       |-- readme_components.rst

... and so on

In conf.py, the sys.path is set to:

import os
import sys
sys.path.insert(0, os.path.abspath('../..'))

The index.rst:

Welcome!
========


.. toctree::
   :maxdepth: 2
   :caption: Modules:


components
readme-components


Indices and tables
==================


* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

the readme_components:

.. include:: ../../README.rst

.. include:: ../../component-1/README.rst

.. include:: ../../component-2/README.rst

The components (only the ones we want to document)

component-1
===========


.. automodule:: components.component-1.orc_component_1.app
   :members:


.. automodule:: components.component-1.orc_component_1.services
   :members:


.. automodule:: components.component-1.orc_component_1.utils
   :members:


component-2
===========


.. and so on

I think it has to do with "-" in the sub-directory names, without being sure. Since multiple people are working on - and using the code I can't change the directory names.

Do you know if there is a way to work around this error and still get the scripts documented? Or if there are some settings in sphinx that can be changed to accommodate this?

Thanks,

Best wishes, Birgitte

mzjn
  • 48,958
  • 13
  • 128
  • 248
Biogitte
  • 303
  • 3
  • 9
  • 2
    Modules whose names contain dashes or hyphens (such as `component-1` and `component-2`) can cause problems. See https://stackoverflow.com/q/761519/407651 – mzjn Aug 30 '19 at 11:41
  • 1
    Same problem here: https://stackoverflow.com/q/55245586/407651 – mzjn Aug 30 '19 at 13:27
  • Also put a blank `__init__.py` file in each of your directory of modules to turn it into a Python package that Sphinx can recognize as such and import. – Steve Piercy Aug 30 '19 at 13:53

0 Answers0