readthedocs / readthedocs.org Goto Github PK

The search page of a built project (for example http://read-the-docs.readthedocs.org/en/latest/search.html) does not work.

If you try to search for something it gets stuck...

This happens in all project I tried.

Thanks,
rubik

I find myself searching for the same docs over and over again.
IMO, it´d be nice to have something like "favourites", letting people flag the docs the usually read. on the index-page, there could be an additional block (if I´m logged in) showing the docs I´ve marked.

I have a project where the Sphinx RST files are in a directory called rst/ and the generated HTML and other documentation is placed in a directory called docs/

readthedocs cannot build documentation for the project and the "Versions" button that normally appears with projects is absent.

If it helps, the project is here: http://readthedocs.org/dashboard/python-csp/

When using :linenos: the resulting line numbers have a padding: http://d.pr/n7WZ

Let people track their docs viewing by using a custom analytics ID on their project/user profile.

This will allow people to have special-cased theme directives or something in their conf.py or setup.py for when their code is running under RTD.

Document this before it goes live so people can take advantage of it.

Hi all,

I've heard about whitelisting, but autodoc extension seems to work for one of my packages (see here: http://readthedocs.org/docs/pymorphy/en/latest/ref/storage_backends.html ) and doesn't work for another ( e.g. here: http://readthedocs.org/docs/django-fab-deploy/en/latest/reference.html ).

Compared http://pip.openplans.org/news.html and http://pip.readthedocs.org/news.html

This can sometimes obscure docs. Starts at bottom. But scrolls with page.

We should probably retry on a build failure or checkout. Then blow away the checkout and re-try it. This would solve the "we changed the backend repo and it didn't show up" problem. As well as fix weird svn/bzr issues we've run into.

For testing purposes, it'd be cool to just use a "docs" branch, or some other branch of git. Otherwise I always need to push into the master, just to test some idea out, to make sure things build at readthedocs.org

I have been unable to reset my password for the past hour. The link that readthedocs.org sends expires immediately. Giving a message that the link has been already used even though I haven't used it.

I have tried using the link as soon as it hits my inbox and waiting a few minutes after it. I always get the following message regardless:

"The password reset link was invalid, possibly because it has already been used. Please request a new password reset."

Please help?

There are some hard-coded domain names for http://readthedocs.org, causing several links in my local deployment to break. It would be nice if these could be relative links, so they continue to work even when run from (say) 127.0.0.1:8000.

From what I can tell, most of these are coming from templates/core/header.html. It looks like most of these could easily be converted to relative links.

currently, the "most viewed pages" are listing every page for a project (e.g., on the first few pages there's a lot of django-cms...).
– that´s useful if I´m the administrator for a project and if I want to know which pages are viewed most. IMO this should be part of my admin-area on rtd.
– for a user it's probably more useful if the page-views are summarized (or if only the index-page is listed). as a user, I´m sometimes taking a look at "most viewed pages" in order to check which projects are obviously interesting for others (a bit like "I´m using this" on djangopackages).

well, just a thought ...

Virtualenv and pip have a triumvirate. We all want access.

I'm trying to set up a RTFD-site internally in my company to host our documentation, but I'm struggling a bit with readthedocs.org (36) and, to a lesser extent, rtfd.org (3) being hard-coded all over the place.

IMHO, this should be configurable, somehow.

(I tried hacking it by adding a variable in readthedocs/settings/base.py, and accessing that in the templates, expecting it to "just work" like SITE_ROOT and friends, but to no avail. Any pointers to where I'm going wrong?)

Hi,

The sphinx website has a section on theming which seems to be talking about the next release: http://sphinx.pocoo.org/theming.html#builtin-themes. I've used it to build the docs for my project stargate http://boothead.github.com/stargate/ locally, but the build failed in rtfd. Would you guys be able to update sphinx, or are you waiting for an actual release?

Cheers,
Ben

Tinkering with faceting support there seem to be only a few packages that actually got indexed with facets in mind.

Not having access to the production scheme, i'd guess a build_solr_schema + restart solr + rebuild index -should- be enough. I hope. I really really hope.

First, thank you very much for creating the awesome readthedocs. Is it possible to generate the PDF version of the documentation and allow it to be downloaded by the readers for offline reading? It would be of great help for users like me in India who don't have continuous access to internet.

I created a new project (bburan/new-era-pump, http://new-era-pump.readthedocs.org/en/latest/). Docs appeared to build correctly the first time. I then edited the readme file to fix some stuff and hit the post-commit hook (http://readthedocs.org/build/696). After waiting a few minutes, I checked the latest docs. It does not appear the build worked since the docs were still on the original version and did not contain the changes I made to the readme file. I checked the build log, but the only thing that jumps out is a Warning:

WARNING: html_static_path entry '/home/docs/sites/readthedocs.org/checkouts/readthedocs.org/user_builds/new-era-pump/checkouts/latest/docs/_static' does not exist

Am I missing something?

I would like to see support for Bazaar (bzr) in addition to git, hg, and svn. This should make it possible to import docs from projects on Launchpad.

For projects that are created on the RTD site (as opposed to those that are imported from a repository), it might be nice to have an option to download an archive of all that project's files.

Use case: I start a new toy project, and throw a few docs up on RTD. But then the project grows, and now I want to grab all my docs and put them in my repository.

Suggested by ojiisan on issue #1

The verbiage on the create and import pages is a little confusing:

Import an existing project: Only use this if you have Sphinx docs in a public repository, you can create new docs via our (import tool).
Create a new project: If you've got a project on a public repository, you can add the docs to Read the Docs via our (import tool).

One of the (import tool) links goes to the "create" page. I think these sentences could be rewritten a little more clearly.

When someone changes their repo, we should be updating the origin of the checkout.

if project.repo_url != git remote -v |grep origin:
system('git remote -d origin && git remote add origin project.repo_url')

or something.

Looks like a fantastic project. I don't know if the backend is modular to support other filetype backends, but I would like to see AsciiDoc support.

I'm getting an error and stack trace when viewing a project's overview page--this seems to occur after editing and saving the project. So far, I have only seen it occur with the Bazaar/Launchpad projects I've created in my local instance, but the stack trace looks like it's all Django stuff. The stack trace is printed by the manage.py runserver output, as well as in the browser window, and the one in the browser doesn't look like an ordinary Django error page (it's just the raw text).

I do have the file it's complaining about in my virtualenv, and the relative pathname it gives is correct in reference to manage.py. Furthermore, the problem goes away if I stop/restart manage.py, so it could just be a quirk of my environment.

IOError: [Errno 2] No such file or directory: '../../lib/python2.6/site-packages/docutils/writers/html4css1/html4css1.css'
Unable to open source file for reading ('../../lib/python2.6/site-packages/docutils/writers/html4css1/html4css1.css').  Exiting.
Traceback (most recent call last):
  File "/home/eric/rtd/lib/python2.6/site-packages/django/core/servers/basehttp.py", line 280, in run
    self.result = application(self.environ, self.start_response)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/core/servers/basehttp.py", line 674, in __call__
    return self.application(environ, start_response)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/core/handlers/wsgi.py", line 241, in __call__
    response = self.get_response(request)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/core/handlers/base.py", line 100, in get_response
    response = callback(request, *callback_args, **callback_kwargs)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/contrib/auth/decorators.py", line 25, in _wrapped_view
    return view_func(request, *args, **kwargs)
  File "/home/eric/rtd/fork/readthedocs.org/projects/views/private.py", line 53, in project_manage
    template_name='projects/project_manage.html',
  File "/home/eric/rtd/lib/python2.6/site-packages/django/views/generic/list_detail.py", line 101, in object_list
    return HttpResponse(t.render(c), mimetype=mimetype)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/__init__.py", line 173, in render
    return self._render(context)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/__init__.py", line 167, in _render
    return self.nodelist.render(context)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/__init__.py", line 796, in render
    bits.append(self.render_node(node, context))
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/debug.py", line 72, in render_node
    result = node.render(context)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/loader_tags.py", line 125, in render
    return compiled_parent._render(context)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/__init__.py", line 167, in _render
    return self.nodelist.render(context)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/__init__.py", line 796, in render
    bits.append(self.render_node(node, context))
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/debug.py", line 72, in render_node
    result = node.render(context)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/loader_tags.py", line 125, in render
    return compiled_parent._render(context)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/__init__.py", line 167, in _render
    return self.nodelist.render(context)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/__init__.py", line 796, in render
    bits.append(self.render_node(node, context))
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/debug.py", line 72, in render_node
    result = node.render(context)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/loader_tags.py", line 125, in render
    return compiled_parent._render(context)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/__init__.py", line 167, in _render
    return self.nodelist.render(context)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/__init__.py", line 796, in render
    bits.append(self.render_node(node, context))
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/debug.py", line 72, in render_node
    result = node.render(context)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/loader_tags.py", line 62, in render
    result = block.nodelist.render(context)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/__init__.py", line 796, in render
    bits.append(self.render_node(node, context))
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/debug.py", line 72, in render_node
    result = node.render(context)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/defaulttags.py", line 253, in render
    return self.nodelist_false.render(context)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/__init__.py", line 796, in render
    bits.append(self.render_node(node, context))
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/debug.py", line 72, in render_node
    result = node.render(context)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/loader_tags.py", line 139, in render
    return self.template.render(context)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/__init__.py", line 173, in render
    return self._render(context)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/__init__.py", line 167, in _render
    return self.nodelist.render(context)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/__init__.py", line 796, in render
    bits.append(self.render_node(node, context))
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/debug.py", line 72, in render_node
    result = node.render(context)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/defaulttags.py", line 251, in render
    return self.nodelist_true.render(context)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/__init__.py", line 796, in render
    bits.append(self.render_node(node, context))
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/debug.py", line 72, in render_node
    result = node.render(context)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/debug.py", line 89, in render
    output = self.filter_expression.resolve(context)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/template/__init__.py", line 579, in resolve
    new_obj = func(obj, *arg_vals)
  File "/home/eric/rtd/lib/python2.6/site-packages/django/contrib/markup/templatetags/markup.py", line 85, in restructuredtext
    parts = publish_parts(source=smart_str(value), writer_name="html4css1", settings_overrides=docutils_settings)
  File "/home/eric/rtd/lib/python2.6/site-packages/docutils/core.py", line 427, in publish_parts
    enable_exit_status=enable_exit_status)
  File "/home/eric/rtd/lib/python2.6/site-packages/docutils/core.py", line 641, in publish_programmatically
    output = pub.publish(enable_exit_status=enable_exit_status)
  File "/home/eric/rtd/lib/python2.6/site-packages/docutils/core.py", line 225, in publish
    sys.exit(exit_status)
SystemExit: 1

readthedocs.org should support git and hg tags to show the documentation of a specific version.

Not so much of an issue if running one's own server, but there doesn't appear to be a way to change one's password on readthedocs.org.

I'm the author of the Sphinx extension doxylink which is hosted as part of the Bitbucket project shhinx-contrib. Sphinx-contrib contains a number of sub-packages, each with their own docs. Doxylink is stored in a subdirectory of the repository. I would like a way to specify to RTD that I want it to only build the docs from that directory in the repo.

This would make most sense as another optional text field in /dashboard/{project}/edit/ where I could just enter "doxylink".

Regards,
Matt Williams

To reproduce:

1. Log into your account at http://readthedocs.org/
2. Select "Change Password" to go to http://readthedocs.org/admin/password_change/, where a standard Django admin login screen is shown
3. Enter RTD username and password to log into admin for changing password. Results in the following message "Please enter a correct username and password. Note that both fields are case-sensitive."

I just tried to add a new project (django-filebrowser) and there´s been some issues:

1. the input-field for project-url should be (a lot) wider.
2. what actually is "project-url"? the url to the project or the url to the docs?
3. IMO "default branch" needs a bit of explanation as well.

thanks,
patrick

I am used to using the top header, with links to modules, index and one level up of the docs. This header is replaced in readthedocs.org. It'd be cool to somehow incorporate it.

It says "SORRY, this page does not exist yet", even though it has built successfully before.

Login in and forcing it to build the latest version doesn't do any good. It continues saying that the latest version was built 6 days ago and pretty much nothing else.

Not sure about what's going on.

I have changed the git url from:

git://github.com/sympy/sympy.git

(this url had some issues with the build, in particular "rst2html" was missing on the readthedocs server, but this is our own problem, we should not call it --- so I have fixed it and before it gets reviewed, I pushed it into my own github) to this url:

git://github.com/certik/sympy.git

but the docs were still failing with the old error. So I tried to remove the project and create it again, but this failed due to:

http://github.com/rtfd/readthedocs.org/issues#issue/1

so I have created a project sympy-docs, with the new git url and that worked!

with google chrome, the vertical alignment of the term "search projects" within the search-bar is wrong (see http://readthedocs.org/views/). looks a bit strange ... with firefox, the term is not being displayed (which is probably the better solution).

I've just finished building documentation for a project and the docs display a "v" as the version.

I am assuming this is because conf.py is not being evaluated and I recall reading a warning about this. Do I need some special permission to get readthedocs to read/execute conf.py ?

If not, is there a way of avoiding that "v" ? It seems all the new projects have that and it is very confusing for users.

I use the sphinxcontrib.bitbucket extension to link to bug reports from my project's history file. That means the docs don't build on readthedocs.org. I understand there's no way you could allow arbitrary extensions to be installed as part of a project build, but is there a way to request that the build server install known-good extensions like the ones in the sphinxcontrib project?

RTD has a somewhat limited ability to parse conf.py files. By default, the scrape_conf_file function in projects/tasks.py uses a regular expression to match desired bits like copyright, html_theme, source_suffix and version. A new conf.py file is written out with these restricted attributes, and this is the one that Sphinx evaluates. This approach has the advantage of avoiding the possibility of arbitrary code execution (which malicious users could take unfair advantage of) but misses many other configuration settings that might exist.

The current workaround to this problem is to "whitelist" specific users, effectively allowing their projects' conf.py files to be evaluated in full. This works well enough, but it's still possible that some destructive code could be added by accident (even by a trusted user). Whitelisting grants too much power for the problem it's trying to solve.

A good middle ground would be to have a safe way to capture all (or very nearly all) of the conf.py settings, while eliminating any potentially destructive executable code. The vast majority of conf.py files are simple name = literal assignments, which can be safely parsed (without evaluating them) by the Python ast module. This would allow even non-whitelisted users to have extensive customizations in their conf.py file, with no risk of arbitrary code execution.

There are times when conf.py legitimately needs arbitrary expressions; for example, when using the sphinx.ext.autodoc extension, it's often necessary to append a particular source code directory to sys.path. This requires importing the sys module, and may also require using the os.path.abspath function. Another example is when autodocumenting a Django application (such as RTD itself), which requires the addition of a few lines to set up the Django environment so its modules can be successfully imported by Sphinx. In these cases, it may work for RTD to automatically guess what's needed and add those lines (thus controlling the "arbitrary" code that gets evaluated), or the whitelisting system could continue to be applied for users who need this functionality.

I've begun working on a solution to this, which I will post to my fork later this week.

It might be handy to have a "Profile" associated with each user. This could be used to set additional information about each user (avatar, personal website, twitter account, bio etc.) but the most immediately useful thing would be having the ability to whitelist a user (and thereby whitelist all their projects), allowing them more control over what's in their docs' conf.py files. Currently, this is done on a project-by-project basis, which can be a chore.

This shouldn't be hard to implement; maybe something like: http://www.b-list.org/weblog/2006/jun/06/django-tips-extending-user-model/

Currently, if docs use the directives automodule, autoclass etc supplied with extension sphinx.ext.autodoc, the docs are unlikely to build correctly.

The first reason is that the source code for the project is not on sys.path, and so autodoc cannot import it and find the docstrings/code that is needed to build the docs. However, even if you special case this module in your Sphinx conf.py, it still won't work if you have third-party dependencies that you import in those modules, because you will get an import error.

For instance, these docs are empty, but shouldn't be, presumably because 'import dulwich" fails on the build machine: http://readthedocs.org/docs/vcs/latest/api/backends/git.html

The following docs do appear, presumably because "import mercurial" happens to succeed on the build machine:
http://readthedocs.org/docs/vcs/latest/api/backends/hg.html

Interestingly, the warnings you would expect don't appear on the build page:
http://readthedocs.org/builds/lukaszb/vcs/427/

(I'm using someone else's package, just in case it was me being dumb, and because that package already does the sys.path hacking in conf.py to get it mainly working).

To build my docs locally, I have to activate the virtualenv that I use for developing my package. Perhaps we need something similar on readthedocs - like "mkvirtualenv $project.$version; setup.py develop". This could be quite an expensive operation though!

For both pip and virtualenv, only the "master" and the latest tagged release actually work. All other versioned links just display the docs from the latest tagged release.

While RTFD.org is absolutely amazing one thing would make this even better: a way to give feedback to documentation (eg let the author know about a typo or request more clarity etc) in some way or another. Be it messaging to the author or comments or whatever, just make it a bit more interactive. Maybe an option to enable/disable comments for docs would be great too.

Right now it's possible to download the docs as a PDF. Would be useful if we could get it as an EPUB book too.

I can't build my docs because when I try to build I get this error:
http://readthedocs.org/builds/pyg/4298/

I don't know what is causing it but I have seen that os.getlogin fails too:
http://readthedocs.org/builds/pyg/4158/

When pulling updates to a project, there's a chance that there will be local, uncommitted modifications (for example if the conf.py file is modified for a whitelisted project). This is already correctly handled for git (via 'reset') and hg (via the -C option) but not for bzr or svn. Both of these should do a 'revert' before 'update' in order to discard any local changes.

I created a project sympy, deleted it and wanted to create it again, but it failed.

I think I recall you mentioning that you use Chef for configuration/deployment.

It would be awesome if you added a generic single-server instance RTD recipe in the repo.

For the sympy documentation, it doesn't seem to be pulling docstrings from the sympy source code:

See e.g. the preview function:

http://readthedocs.org/projects/certik/sympy-docs/docs/modules/printing.html#preview

and the source code, that should pull the docstring:

http://readthedocs.org/projects/certik/sympy-docs/docs/_sources/modules/printing.txt

and here is how it is supposed to look:

http://docs.sympy.org/modules/printing.html#module-sympy.printing.preview

Maybe it's just my shitty eyes, but I'd really appreciate a bit more contrast/decoration on links in the default theme, especially in the table of contents.

See http://cl.ly/3j410O2y3X1S2j0t2n3g for what I'm talking about.

It'd be nice to put the link to:

http://github.com/rtfd/readthedocs.org

somewhere on the main page of:

http://readthedocs.org/

or at least at http://readthedocs.org/dashboard/, so that people can report bugs and send patches.