Readthedocs.org: Module members documentation isn't picked up

[marciof]

Looks like documentation added to module-level members isn't picked up, making them appear to use their initialization value's documentation.

For example, I have a module that documents two globals, __features__ and __version__. Running sphinx-build locally produces the correct documentation, while its Read the Docs page doesn't.

[ericholscher]

This is covered in the FAQ: http://docs.readthedocs.org/en/latest/faq.html#my-project-isn-t-building-with-autodoc and http://docs.readthedocs.org/en/latest/faq.html#i-get-import-errors-on-libraries-that-depend-on-c-modules

[marciof]

@ericholscher, are we referring to the same problem? What the FAQ mentions are build errors, of which I get none:

• https://readthedocs.org/builds/argf/1890066/
• https://readthedocs.org/builds/argf/1890069/

I have tried two different documentation formats:

• https://github.com/marciof/argf/commit/98fcd6a8c80d50f4aeac4bfc42063f94f8ff842a
• https://github.com/marciof/argf/commit/11c4718ce550daab56c50379d949350782861853

But it's still not picked up: http://argf.readthedocs.org/en/latest/#reference

[marciof]

@ericholscher, ping.

[swistakm]

I think this issue was closed prematurely as it really exists and documentation doesn't help in fixing it.

I was struggling with this recently and spend many hours digging through sphinx and RTD code and running countless builds in order to understand and find solution.

What happens?
If module has attributes documented using following syntax supported by autodoc:

#: module member FOO documentation as comment
FOO = 1

BAR = 1
"""module member BAR documentation as semi-docstring"""

It should be picked by Sphinx autodoc extension. It was indeed in my local development builds and documentation generated properly when I have used something like:

.. automodule:: mymodule
   :members:

Anyway, the documentation for module members was not generated on RTD build. I have even traced logs for autodoc-skip-member signal to see if it collects my module members. It collected them and even did not skip them.

Why does it happen?

Finally I found explanation. Problem lies in the requirement for autodoc to see sources of the module in order to generate documentation of module and class members. Packages on RTD are by default installed with:

python setup.py install --force

In this case autodoc obviously won't be able to see sources. It will not pick module and class members.

How to solve it?

Surprisingly solution is pretty straightforward: do not install package in development mode. This means disabling the _"Install your project inside a virtualenv using setup.py install"_ option in _Advanced settings_. The package just needs to be in Sphinx path in order to be imported and documented. This can be achieved by simple sys.path modification in conf.py.

But there is a catch: this won't work for projects implementing extensions, but only for vanilla Python packages that have their requirements properly installed with requirements file. Projects with extensions need to be built and this requires using setup.py script. RTD FAQ entry about having setup script in place other than root already gives a clue to final fix.

Members documentation with autodoc in order to work requires installation in development mode. Fortunately pip already supports specifying filesystem locations as packages installed in "development mode". Instead of doing:

``` requirements.txt

for package in root

.

for package in other place

src/or/maybe/even/deeper/

You need to use `-e` prefix

for package in root

-e.

for package in other place

-e./src/or/maybe/even/deeper/

**What can be done about that**

I think it is worth to reopen this issue in the first place because this problem exists, it in unobvious, it is undocumented, and already few programmers struggled with it without finding any solution.

The easiest thing that can be done is extending FAQ with short problem and solution description. Maybe this FAQ could link to this issue.

Obviously my fix is far from perfection, it depends on relative filesystem paths and can be easily broken if rtd runner implementation changes (e.g. change in cwd for `pip` command). Anyway using relative paths in requirements file was already mentioned in FAQ as a solution to other issue so I think this is not a big deal.

The best if we could install package in development mode. This could either replace default behaviour of installation command or be another option in _Advanced settings_. I personally do not care about UX here.

Personally I think that installing in "development mode" could be even a default behaviour. I don't see where it could break anything. Also it would not require extending the documentation/FAQ as it would fix every existing build with such autodoc problem.

**Sidenotes**

**Proof of concept:** [this line](https://github.com/swistakm/pyimgui/blob/master/doc/requirements-docs.txt#L8) in my project proves that installing the project in development mode solves the problem of undocumented module members.

**Other related issues:** it seems that installing the project in development mode could also solve other issues like "autodoc order by source" (see: #1162)

**Project installation command:** I have noticed that project dependencies are installed with `pip` but the project itself is installed with good old `python setup.py install`. I think project installation could be replaced with `pip` call too:

pip install .

It would also make switching do development mode easier:

pip install -e .
```

[remidebette]

This problem should not be Closed.
I am having the exact same issue with both "order by source" #1162 and "getting class attributes Docstring" not working with Read the docs.

There is no clear and working answer.
The Sphinx version is 1.6.2

[tdryer]

Related to #3193.

[stsewd]

If this can be solved by installing with pip, we already support that https://docs.readthedocs.io/en/latest/yaml-config.html#python-pip-install

[stsewd]

Can someone try https://github.com/rtfd/readthedocs.org/issues/855#issuecomment-415852721? If that doesn't work, we can consider using the -e option on pip. I can't build the projects linked here btw.

[stsewd]

Closing this as the user hasn't responded or given more information, feel free to reopen with more information if you are still having this problem :).