Add support for automodule/autoclass etc. about readthedocs.org HOT 27 CLOSED

So. I'm curious what you're suggesting that we do exactly.

Currently, if you import your project straight away with autodoc, it won't work because that requires running arbitrary code.

If we white list your user account, your conf.py files aren't cleaned up, and so everything that would normally work still works. So if you edit the sys.path in the conf.py, and don't have external dependencies, it should build fine.

If we automagically added the project's directory to the sys.path, I feel we would be doing a disservice to the project maintainers, because they wouldn't make their documentation actually build correctly for everyone else.

The only other option that I can think of (and you mention), is to create a virtualenv for each project, install the project into the venv, pulling in it's dependencies, and then building the documentation from the source package.

This could probably be done, but it seems like a lot of work to support very few packages. Especially as we have added versions, and will add branch support in the future, that would be a good amount of processing power.

I could probably be convinced to do this, but it seems like a lot of work to support few packages.

from readthedocs.org.

Yes, I understand that it would be a lot of work, and potentially very expensive.

Some smaller potential steps:

• find out rouhgly how many projects actually use autodoc
• make autodoc warnings appear (I don't know why they are surpressed, they appear when I run Sphinx locally).
• add some warnings that mention that autodoc won't work.

For me, the biggest bug was actually that the documentation appeared to build correctly, but various bits were missing, and there were no warnings before or after that this might be/was a problem.

from readthedocs.org.

Hmm, apparently I 'closed' this bug. I don't know how I did that, or how to undo it - can't find any UI for that. I still think there are some action points that are worth considering, if the main one is two expensive.

from readthedocs.org.

I pulled all the docs from your servers, and did some grepping:

Of the 169 projects that actually have docs, 42 are using at least 1 autodoc directive (automodule, autoclass etc.) That's nearly 25%. There are 1774 autodoc directives overall - on average over 40 per project that uses autodoc.

Almost all of these are going to be broken and missing some very large chunks of documentation. I think 25% is certainly worth worrying about, especially as there are no warnings, and nothing even in the docs themselves to say that something is missing.

I would suggest at the very least:

1. A warning, when people are adding docs, that anything with autodoc will not be built correctly
2. A patch for Sphinx (somehow) that will cause a warning to be inserted in the docs when something couldn't be found.

Please don't hate me for reporting this! I just care about documentation, and docs that have been built incorrectly and are missing a lot is a big deal. As soon as I found this I deleted the docs for my project, because having an incomplete set of docs does my project a big misservice, and I can upload a correct set to packages.python.org.

Here are the affected projects, BTW:

booleanpy
boto
celery
cli
csvsee
dango-uni-form
distutils2
django-admin-tools
django-denorm
django-formwizard
django-gencal
django-guardian
django-layar
django-native-tags
django-page-cms
django-permissions
django-phased
django-resources
django-scaffold
easy-thumbnails
fabric
feincms
flask
kombu
lightning-fast-cms
lightning-fast-shop
logbook
micromodels
pymorphy
python-configman
python-handler-socket
python-storymarket
read-the-docs
readthedocs-doc-ja
sphinx
sqlalchemy
stargate
stub
sympy
vcs
webtoolbox
woven

from readthedocs.org.

Documentation with autodoc works just fine. If the user is white listed (something we have to do on the backend, so that there is no arbitrary code execution). If they are correctly setting the sys.path in their conf.py, so that the documentation builds, it will work just fine.

If there are autodoc warnings, they will indeed show up in the build output. I don't really know what you're talking about?

http://readthedocs.org/builds/boothead/stargate/1445/ shows the autodoc errors because the user didn't set their sys.path correctly.

http://sympy.readthedocs.org/modules/core.html is an example of autodoc working perfectly fine. I bet if you actually read the documentation on our site for most of these projects, I bet they are working fine.

I agree that the whitelisting process could be more exposed (it's not really mentioned on the site). But allowing autodoc on any arbitrary repo seems like a really bad idea. There is a reason that we have done things this way. I'd be happy with suggestions (or patches) that improve this situation, other than exposing the limitations in the UI (which needs to be done ASAP).

from readthedocs.org.

OK, sorry, we seem to be mis-communicating.

I didn't know before what you meant by white-listing. There is nothing in the interface about this, so I had no idea what you meant - I thought you were speaking hypothetically.

I did spot checks on some of the projects listed, and all the initial ones I found were like my own, where there big chunks of documentation missing but no errors shown in the documentation itself to say "you are missing something important here!". For example:

http://readthedocs.org/docs/cli/latest/ (see API section at end)
http://readthedocs.org/docs/logbook/latest/api/base.html

I have since discovered some that some projects build correctly.

Regarding errors in the build standard output/error - sorry, they are there, I think I was confused by different errors - you get an error about the directive not being known - I now realise this is because you delete the conf.py unless the project is whitelisted. I think this is an important disclaimer to be added somewhere prominent.

There are also some projects that include dependencies and still work e.g. Flask - which doesn't even set sys.path correctly:

https://github.com/mitsuhiko/flask/blob/master/docs/conf.py

And imports modules from outside standard lib:

https://github.com/mitsuhiko/flask/blob/master/flask/app.py

But is built right:

http://readthedocs.org/docs/flask/latest/api.html

from readthedocs.org.

I also realised why I thought the errors were not appearing on the build log output. On this page, for example: http://readthedocs.org/builds/lukaszb/vcs/427/

... the text ** (ERROR/3) Unknown directive type "automodule". ** is hidden off the right hand side of the page, and it looks like debugging output, rather than an error. Sorry for the noise on that one.

from readthedocs.org.

I went ahead and committed basic text that will alert people on the Import page.

I also went through and whitelisted all the users in the system already, as nobody has tried anything funny, and am in the process of rebuilding all the docs (should take ~20 minutes). So at least the parts that we weren't informing users about will be fixed, if the docs are correct.

Now new users will see the warning at the top of the import page (you won't, because your account is now whitelisted). I'd like to figure out a good way to not have to do this, but that will require more thinking.

At least this will hopefully make it less invisible this will happen. I'll keep this ticket open because the problem isn't all the way fixed, but it should at least be better than before. Thanks for kicking my ass into gear.

from readthedocs.org.

Hi !

From what I understood reading this thread, those errors that I got when trying to build my project (http://readthedocs.org/projects/spiteat/) :

(ERROR/3) Unknown directive type "automodule".

Come from the fact that I am not whitelisted ... and because of that, you generate a 'conf.py' file to build my project.
If that's the case, is there any reason why you don't you activate 'autodoc' extension in this generated 'conf.py' ?

Cheers,

Sébastien

from readthedocs.org.

Yea. This is because of the fact that autodoc executes arbitrary code, so anyone might be able to come onto the site and put a repo in that does something harmful.

I've been looking into pypy's sandbox mode to see if I can take away this restriction, because it sucks a lot.

I have whitelisted your user now, so you should be fine from here out.

from readthedocs.org.

Ok great !

Yeah ... that's really a pity evilness is all around ! Because of those guys, we cannot even trust a poor autodoc.
That might be the crapiest solution ever, but have you considered replacing the import function from your generated "conf.py", by something like : http://dpaste.com/469929/
I have no idea if you clearly know which modules are potentially harmful, but if you do, you could just replace them in builtin by dummy modules !? Yes that's ugly ... But that could be a temporary fix...

from readthedocs.org.

Hi, I know this is a closed ticket but I've encountered the same issue -- I'm user okfn on readthedocs. I've looked around the docs and the site but can't see how to request to get whitelisted. Am I missing something and please could you whitelist 'okfn'?

BTW: ReadTheDocs is great!

from readthedocs.org.

Whitelisted. Things should work now. If they don't check your build output
to see if you have dependencies and need to add to a requirements file.

On Mon, Aug 8, 2011 at 1:51 AM, rgrp <
[email protected]>wrote:

Hi, I know this is a closed ticket but I've encountered the same issue --
I'm user okfn on readthedocs. I've looked around the docs and the site but
can't see how to request to get whitelisted. Am I missing something and
please could you whitelist 'okfn'?

BTW: ReadTheDocs is great!

Reply to this email directly or view it on GitHub:
#26 (comment)

Eric Holscher
Engineer at Urban Airship in Portland, Or
http://ericholscher.com

from readthedocs.org.

I have the same problem. Is there a standard procedure to be whitelisted? my username on readthedocs is 'gabrielelanaro'

from readthedocs.org.

I'm having the same issue. could you please whitelist my user maraujop?

from readthedocs.org.

I'm having the same issue. autodoc seems to be a pretty core aspect of sphrinx and hence something I was expecting to work. I'm not going to restructure my documentation to get around this. Can I be whitelisted please? gyllstromk

from readthedocs.org.

Me too. Maybe we should implement some "please whitelist me" button?

from readthedocs.org.

Can you please whitelist xaralis, we are using automodule in Ella's docs :(

https://github.com/ella/ella

from readthedocs.org.

Done.

On Wed, Feb 1, 2012 at 8:16 AM, xaralis <
[email protected]

wrote:

Can you please whitelist xaralis, we are using automodule in Ella's
docs :(

https://github.com/ella/ella

---

Reply to this email directly or view it on GitHub:
#26 (comment)

Eric Holscher
Engineer at Urban Airship in Portland, Or
http://ericholscher.com

from readthedocs.org.

Hi, Can you please add me to the white list? My username is duanemalcolm. Cheers.

from readthedocs.org.

Done.

On Tue, Feb 7, 2012 at 3:15 PM, Duane Malcolm <
[email protected]

wrote:

Hi, Can you please add me to the white list? My username is duanemalcolm.
Cheers.

---

Reply to this email directly or view it on GitHub:
#26 (comment)

Eric Holscher
Engineer at Urban Airship in Portland, Or
http://ericholscher.com

from readthedocs.org.

Hey what about me? :-)

from readthedocs.org.

Thanks Eric. Great idea, great website.

from readthedocs.org.

Any updates on this ? I'm facing this issue right now.

from readthedocs.org.

Forget, my mistake.

from readthedocs.org.

can you please whitelist jfburkhart.

from readthedocs.org.

I realize this issue is closed, but I am having problems with autodoc in my build. Has autodoc support been added to ReadTheDocs? I wasn't able to find anything explicitly in the documentation. My username on ReadTheDocs is swainn and the project I'm trying to build is here: https://bitbucket.org/swainn/gsshapy/src

from readthedocs.org.