Sphinxcontrib-napoleon is not able to generate the documentation

[rikirenz]

It seems that Sphinxcontrib-napoleon is not able to generate the documentation for the functions with the pytest-bdd decorators.

These are the packages versions:

pytest-bdd==2.18.1
sphinxcontrib-napoleon==0.6.1

This is the stack trace:

$ make -C docs html  
make: Entering directory `/code/docs'
sphinx-apidoc -f -o _source ../inspirehep; \
rm -f _source/modules.rst; \
sphinx-build -w documentation_errors.log -b html -d _build/doctrees   . _build/html
Creating file _source/inspirehep.rst.
Creating file _source/inspirehep.bat.rst.
Creating file _source/inspirehep.bat.pages.rst.
Creating file _source/inspirehep.bat.steps.rst.
Creating file _source/inspirehep.dojson.rst.
Creating file _source/inspirehep.dojson.common.rst.
Creating file _source/inspirehep.dojson.conferences.rst.
Creating file _source/inspirehep.dojson.data.rst.
Creating file _source/inspirehep.dojson.experiments.rst.
Creating file _source/inspirehep.dojson.hep.rst.
Creating file _source/inspirehep.dojson.hep.rules.rst.
Creating file _source/inspirehep.dojson.hepnames.rst.
Creating file _source/inspirehep.dojson.institutions.rst.
Creating file _source/inspirehep.dojson.jobs.rst.
Creating file _source/inspirehep.dojson.journals.rst.
Creating file _source/inspirehep.dojson.utils.rst.
Creating file _source/inspirehep.modules.rst.
Creating file _source/inspirehep.modules.api.rst.
Creating file _source/inspirehep.modules.api.v1.rst.
Creating file _source/inspirehep.modules.arxiv.rst.
Creating file _source/inspirehep.modules.authors.rst.
Creating file _source/inspirehep.modules.authors.dojson.rst.
Creating file _source/inspirehep.modules.authors.dojson.fields.rst.
Creating file _source/inspirehep.modules.authors.rest.rst.
Creating file _source/inspirehep.modules.authors.views.rst.
Creating file _source/inspirehep.modules.cache.rst.
Creating file _source/inspirehep.modules.converter.rst.
Creating file _source/inspirehep.modules.crossref.rst.
Creating file _source/inspirehep.modules.disambiguation.rst.
Creating file _source/inspirehep.modules.fixtures.rst.
Creating file _source/inspirehep.modules.forms.rst.
Creating file _source/inspirehep.modules.forms.fields.rst.
Creating file _source/inspirehep.modules.forms.validators.rst.
Creating file _source/inspirehep.modules.hal.rst.
Creating file _source/inspirehep.modules.literaturesuggest.rst.
Creating file _source/inspirehep.modules.literaturesuggest.fields.rst.
Creating file _source/inspirehep.modules.migrator.rst.
Creating file _source/inspirehep.modules.migrator.tasks.rst.
Creating file _source/inspirehep.modules.orcid.rst.
Creating file _source/inspirehep.modules.pidstore.rst.
Creating file _source/inspirehep.modules.records.rst.
Creating file _source/inspirehep.modules.records.mappings.rst.
Creating file _source/inspirehep.modules.records.serializers.rst.
Creating file _source/inspirehep.modules.records.serializers.schemas.rst.
Creating file _source/inspirehep.modules.references.rst.
Creating file _source/inspirehep.modules.search.rst.
Creating file _source/inspirehep.modules.search.walkers.rst.
Creating file _source/inspirehep.modules.theme.rst.
Creating file _source/inspirehep.modules.tools.rst.
Creating file _source/inspirehep.modules.workflows.rst.
Creating file _source/inspirehep.modules.workflows.actions.rst.
Creating file _source/inspirehep.modules.workflows.mappings.rst.
Creating file _source/inspirehep.modules.workflows.tasks.rst.
Creating file _source/inspirehep.modules.workflows.views.rst.
Creating file _source/inspirehep.modules.workflows.workflows.rst.
Creating file _source/inspirehep.utils.rst.
Creating file _source/modules.rst.
Running Sphinx v1.5.5
loading pickled environment... failed: source directory has changed
loading intersphinx inventory from https://docs.python.org/objects.inv...
intersphinx inventory has moved: https://docs.python.org/objects.inv -> https://docs.python.org/2/objects.inv
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 65 source files that are out of date
updating environment: 65 added, 0 changed, 0 removed
reading sources... [100%] tools                                                                     
/code/docs/_source/inspirehep.bat.steps.rst:10: WARNING: invalid signature for autofunction (u'inspirehep.bat.steps.given::pytestbdd_given_I am logged in')
/code/docs/_source/inspirehep.bat.steps.rst:10: WARNING: don't know which module to import for autodocumenting u'inspirehep.bat.steps.given::pytestbdd_given_I am logged in' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
/code/docs/_source/inspirehep.bat.steps.rst:18: WARNING: invalid signature for autofunction (u'inspirehep.bat.steps.then::pytestbdd_then_I should see {expected_data} in the input box with id {field_id}')
/code/docs/_source/inspirehep.bat.steps.rst:18: WARNING: don't know which module to import for autodocumenting u'inspirehep.bat.steps.then::pytestbdd_then_I should see {expected_data} in the input box with id {field_id}' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
/code/docs/_source/inspirehep.bat.steps.rst:26: WARNING: invalid signature for autofunction (u'inspirehep.bat.steps.when::pytestbdd_when_I click on the button with id {button_id}')
/code/docs/_source/inspirehep.bat.steps.rst:26: WARNING: don't know which module to import for autodocumenting u'inspirehep.bat.steps.when::pytestbdd_when_I click on the button with id {button_id}' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
/code/docs/_source/inspirehep.bat.steps.rst:26: WARNING: invalid signature for autofunction (u'inspirehep.bat.steps.when::pytestbdd_when_I click on the link with text {text_value}')
/code/docs/_source/inspirehep.bat.steps.rst:26: WARNING: don't know which module to import for autodocumenting u'inspirehep.bat.steps.when::pytestbdd_when_I click on the link with text {text_value}' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
/code/docs/_source/inspirehep.bat.steps.rst:26: WARNING: invalid signature for autofunction (u'inspirehep.bat.steps.when::pytestbdd_when_I insert <input> in the input box with id {field_id}')
/code/docs/_source/inspirehep.bat.steps.rst:26: WARNING: don't know which module to import for autodocumenting u'inspirehep.bat.steps.when::pytestbdd_when_I insert <input> in the input box with id {field_id}' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
/code/docs/_source/inspirehep.bat.steps.rst:26: WARNING: invalid signature for autofunction (u'inspirehep.bat.steps.when::pytestbdd_when_I insert {input_autocompletion} in the autocomplete input box with id {autocompletion_field}')
/code/docs/_source/inspirehep.bat.steps.rst:26: WARNING: don't know which module to import for autodocumenting u'inspirehep.bat.steps.when::pytestbdd_when_I insert {input_autocompletion} in the autocomplete input box with id {autocompletion_field}' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
/code/docs/_source/inspirehep.bat.steps.rst:26: WARNING: invalid signature for autofunction (u'inspirehep.bat.steps.when::pytestbdd_when_I insert {input} in the input box with id {field_id}')
/code/docs/_source/inspirehep.bat.steps.rst:26: WARNING: don't know which module to import for autodocumenting u'inspirehep.bat.steps.when::pytestbdd_when_I insert {input} in the input box with id {field_id}' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
/code/docs/_source/inspirehep.bat.steps.rst:26: WARNING: invalid signature for autofunction (u'inspirehep.bat.steps.when::pytestbdd_when_I select the value {input_select} in the select box with id {field_id}')
/code/docs/_source/inspirehep.bat.steps.rst:26: WARNING: don't know which module to import for autodocumenting u'inspirehep.bat.steps.when::pytestbdd_when_I select the value {input_select} in the select box with id {field_id}' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] tools                                                                      
generating indices... genindex py-modindex
highlighting module code... [100%] wtforms.fields.core                                              
writing additional pages... search
copying images... [100%] images/xquartz_security.jpg                                                
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 16 warnings.
Build Failed. Check documentation_errors.log file for details.
make: *** [html] Error 1
make: Leaving directory `/code/docs'

Do you have any ideas?

[bubenkoff]

well, i would simply exclude the bdd code completely from sphinx, why would you need the automatic docs for bdd stuff?

[rikirenz]

Well the idea is that people that want to write tests with pytest-bdd should not read the code to know all the steps. They should read the doc and see the steps from there.

[bubenkoff]

the use case makes sense, just not sure if it's possible without custom plugin for sphinx from the error report you gave it complaints about the module of the step, but we do set the module actually, so not sure what's the actual problem. Might be the spaces in the function name, which we use

[rikirenz]

I think anyway that there isn't a way to avoid the usage of spaces in pytest-bdd decorators. I will try to open an issue in the sphinx project and see what happen. I will update this issue if I am going to find a solution.

For now the best solution is: ignoring the pytest-bdd functions when the sphinx generation runs.