Opened 6 years ago

Closed 5 years ago

#7507 closed defect (wontfix)

Sphinx warnings about "missing attribute mentioned"

Reported by: atagar Owned by: atagar
Priority: Low Milestone:
Component: Core Tor/Stem Version:
Severity: Keywords: website
Cc: Actual Points:
Parent ID: Points:
Reviewer: Sponsor:

Description

Stem's sphinx compilation for its docs complains about modules with an all attribute...

...
reading sources... [100%] api/util/tor_tools
/home/atagar/Desktop/stem/docs/api/control.rst:9: WARNING: missing attribute mentioned in :members: or __all__: module stem, attribute connection
/home/atagar/Desktop/stem/docs/api/control.rst:9: WARNING: missing attribute mentioned in :members: or __all__: module stem, attribute process
/home/atagar/Desktop/stem/docs/api/response.rst:4: WARNING: missing attribute mentioned in :members: or __all__: module stem.response, attribute events
/home/atagar/Desktop/stem/docs/api/response.rst:4: WARNING: missing attribute mentioned in :members: or __all__: module stem.response, attribute getinfo
/home/atagar/Desktop/stem/docs/api/response.rst:4: WARNING: missing attribute mentioned in :members: or __all__: module stem.response, attribute getconf
/home/atagar/Desktop/stem/docs/api/response.rst:4: WARNING: missing attribute mentioned in :members: or __all__: module stem.response, attribute protocolinfo
/home/atagar/Desktop/stem/docs/api/response.rst:4: WARNING: missing attribute mentioned in :members: or __all__: module stem.response, attribute authchallenge
looking for now-outdated files... none found
...

We should look into what these warnings are trying to tell us, and figure out if there's something we can either do to fix or suppress it.

Child Tickets

Change History (2)

comment:1 in reply to:  description Changed 5 years ago by eoinof

There are 2 main issues.

1) WARNING: Duplicate explicit target name: "ticket".

This can be fixed by using a diferent target name for each different link
e.g. instead of:

(ticket <https://trac.torproject.org/1101>_)

use:

(ticket 1101 <https://trac.torproject.org/1101>_)

If anyone has a preference for the best name to use I'll put together a
github commit.

2) WARNING: missing attribute.

These are caused by the all list in the different init.py files
Sphinx uses the all list to check every module is loaded, but in some cases
it is not and the warning is generated.
One way to fix this would be to get rid of the all list in each init.py
file, though that would prevent someone from writing code like:

from stem import * 

For example the stem.process module is not loaded by any other module so when
sphinx runs it cannot match the module as described in all

These are the current warnings from sphinx.

sphinx-build -b html -d _build/doctrees   . _build/html
Making output directory...
Running Sphinx v1.1.3
loading pickled environment... not yet created
building [html]: targets for 34 source files that are out of date
updating environment: 34 added, 0 changed, 0 removed
reading sources... [100%] tutorials/tortoise_and_the_hare                                                                            
/home/eoin/stemClean/stem/docs/api/connection.rst:2: WARNING: Duplicate explicit target name: "ticket".
/home/eoin/stemClean/stem/docs/api/control.rst:9: WARNING: missing attribute mentioned in :members: or __all__: module stem, attribute process
/home/eoin/stemClean/stem/docs/api/descriptor/descriptor.rst:4: WARNING: missing attribute mentioned in :members: or __all__: module stem.descriptor.__init__, attribute export
/home/eoin/stemClean/stem/docs/api/descriptor/descriptor.rst:4: WARNING: missing attribute mentioned in :members: or __all__: module stem.descriptor.__init__, attribute reader
/home/eoin/stemClean/stem/docs/api/descriptor/descriptor.rst:4: WARNING: missing attribute mentioned in :members: or __all__: module stem.descriptor.__init__, attribute extrainfo_descriptor
/home/eoin/stemClean/stem/docs/api/descriptor/descriptor.rst:4: WARNING: missing attribute mentioned in :members: or __all__: module stem.descriptor.__init__, attribute server_descriptor
/home/eoin/stemClean/stem/docs/api/descriptor/descriptor.rst:4: WARNING: missing attribute mentioned in :members: or __all__: module stem.descriptor.__init__, attribute microdescriptor
/home/eoin/stemClean/stem/docs/api/descriptor/descriptor.rst:4: WARNING: missing attribute mentioned in :members: or __all__: module stem.descriptor.__init__, attribute networkstatus
/home/eoin/stemClean/stem/docs/api/descriptor/descriptor.rst:4: WARNING: missing attribute mentioned in :members: or __all__: module stem.descriptor.__init__, attribute router_status_entry
/home/eoin/stemClean/stem/docs/api/response.rst:4: WARNING: missing attribute mentioned in :members: or __all__: module stem.response, attribute getinfo
/home/eoin/stemClean/stem/docs/api/response.rst:4: WARNING: missing attribute mentioned in :members: or __all__: module stem.response, attribute getconf
/home/eoin/stemClean/stem/docs/api/response.rst:4: WARNING: missing attribute mentioned in :members: or __all__: module stem.response, attribute protocolinfo
/home/eoin/stemClean/stem/docs/api/response.rst:4: WARNING: missing attribute mentioned in :members: or __all__: module stem.response, attribute authchallenge
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] tutorials/tortoise_and_the_hare                                                                             
writing additional files... (31 module code pages) _modules/index
 genindex py-modindex search
copying images... [100%] _static/buttons/tutorials.png                                                                               
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded, 13 warnings.

Build finished. The HTML pages are in _build/html.

comment:2 Changed 5 years ago by atagar

Resolution: wontfix
Status: newclosed

Hi Eoin, thanks for looking into this!

1) WARNING: Duplicate explicit target name: "ticket".
This can be fixed by using a diferent target name for each different link

The cure sounds worse than the disease in this case. It's common to want to have multiple links with the same text. If sphinx produces a warning for this then it's probably best ignored.

2) WARNING: missing attribute.
These are caused by the all list in the different init.py files

Ahhhh, makes sense. We definitely don't want to drop the all since that would have a functional impact on our users. Sounds like this is another warning that's best ignored.

If there's a configuration option to selectively disable these two warnings then that would be great. Barring that guess I'll just keep ignoring them - thanks for the explanations!

Note: See TracTickets for help on using tickets.