Develop Reference

autosummary “toctree contains reference to nonexisting document” warnings

I am facing the same problem as in this thread. When I build my Sphinx documentation with make html then I get a lot of warnings like this
None:None: WARNING: toctree contains reference to nonexisting document u'cars.Car.time_elapsed'
I am using html_theme = 'sphinx_rtd_theme'. If I change it to classic, then I don't get the warnings. If I add numpydoc_show_class_members = False to conf.py, then I don't get them either.
BUT; I really like sphinx_rtd_theme and when I use classic or add numpydoc_show_class_members = False, then a 'TOC' of my Python methods are removed, which I prefer staying (see the red box in the image) .
The documentation of the cars module is made by
.. automodule:: cars
:members:
The module contains a single class Car with two methods. The docstrings are written in numpydoc.

It seems to me that you are currently using the numpydoc extension. Please note that Numpy and Google style docstrings are now supported by the builtin sphinx.ext.napoleon extension.
Removing the numpydoc extension and using sphinx.ext.napoleon will likely solve your problem.
Sources
Napoleon - Marching toward legible docstrings
Sphinx Doc - Support for NumPy and Google style docstrings

using :ref: in Python docstrings using Sphinx

I'm using Sphinx to document a python project, and I'm trying to create a reusable tip to be used in several locations.
Typically, I'll use the following syntax in a python file:
"""
.. tip::
I want this tip to be used in several locations. Why?
- Save time
- Work less
"""
Now this works whether I put it at the beginning of the file, right under class definition or right under function definition.
I found Sphinx's manual for :ref:, which suggests to use a label:
.. _my_reusable_tip:
.. tip::
...
And then call this tip with :ref:`my_reusable_tip` anywhere I want.
The manual states that 'it works across files, when section headings are changed, and for all builders that support cross-references'
The thing is, it doesn't matter in which .py file in the project I write the label and tip definition, the :ref:`my_reusable_tip` just displays 'my_reusable_tip', and not the tip itself.
What I'm using to build the documentation is
sphinx-apidoc -f -F -o
make html
I'm pretty sure my logic is flawed in some way, but I can't figure out why.
I know that Sphinx searches the project for reStructuredText and renders it if it can, but I think I'm missing something here.
I tried to add this label in a seperate .py file enclosed in """, and in a separate .txt file without enclosed """.
I tried creating an .rst file with the label definition and rebuild the html documentation.
What am I missing here?
Python 3.4.3 BTW.

In sphinx, a :ref: is simply a more robust way of linking (or referencing) another part of the document. Thus, your use of :ref: will simply provide a hyperlink to the label.
It is not a way of substituting or expanding a block.
Inline substitutions are available using using |...|, however an inline substitution cannot be used to substitute a block as you seem to require.
RestructuredText is not a template language, and thus doesn't provide macro like facilities. In the event you need it, an alternative solution is to use a template library such as mako or jinja to deal with this kind of issue.

Just using reStructuredText directive
.. include:: ./my_reusable_tip.txt
in your rst files?

Documenting parameters with long descriptions in Sphinx

I'm documenting my Python classes using Sphinx, and sometimes I want to give my parameters quite long descriptions to explain something in details. Unfortunately, Sphinx generates ugly output for me which wastes a lot of space and breaks the whole page appearance:
It can be seen that Sphinx creates a table, then puts "Parameters" header to the left cell, and the actual list of parameters to the right cell. But there should be way to avoid creating this table completely. After playing with the page DOM tree I finally can show that I want to achieve:
Is there a built-in way to do this or I'd have to create a PR to Sphinx theme or Sphinx itself?

After posting an issue to Sphinx bug-tracker and having no response, I've decided to roll-out my own solution (better say, hack). To achieve the look I want, I have written a simple Sphinx extension which post-processes generated HTML code. It can be found on PyPI:
https://pypi.python.org/pypi/sphinxcontrib.divparams
https://pythonhosted.org/sphinxcontrib.divparams/
This doesn't seem to be the best way to solve the issue, but the behaviour I wanted to change is deeply hard-coded in docutils, not Sphinx.

How can I use both Sphinx and Pycco for Python documentation?

I'd like to be able to use Sphinx for the main project documentation, so the docstrings must be in reStructuredText, but I'd also like to generate HTML for reading the inline comments in the style of Pycco, which uses Markdown.
Is there a tool or combination of tools that will allow me to do convert only the docstrings from reStructuredText to Markdown?

The pyment tool can convert docstrings to different formats. You could start with that, and then write a subclass of DocToolsBase to format docstrings the way you like.
See this question What is the standard Python docstring format? for more about python docstring conventions and tooling.

A software called Pandoc may be the right tool. You can see the detail in the page through the hyperlink. I ever wanted to have try of it, but it needs Haskell runtime environment which is a little big, so I gave up.

Parsing .rst files with Sphinx-specific directives programmatically

I would like to be able to parse sphinx based rst in Python for further processing and checking. Something like:
import sphinx
p = sphinx.parse("/path/to/file.rst")
do_something_with(p)
It seems that something is possible in docutils using the docutils.core.publish_file:
publish_file(open("/path/to/file.rst")
But that doesn't know anything about sphinx specific directives etc...

You can use Sphinx Extensions to do custom processing before the final write. There is a very good getting started example project in the documentation that discusses various hooks that allow you to customize Sphinx.
Depending on what you're trying to do, you may need to supply your do_something function as a call back argument to one of these events.
doctree-resolved(app, doctree, docname)
html-page-context(app, pagename, templatename, context, doctree)
And then you can extend sphinx as follows
def setup(app):
app.connect('doctree-resolved', do_something)
If the example in the Sphinx tutorial is not detailed enough, Doug Hellmann also has a blog post about creating a spell checker for Sphinx. I found it to be a useful reference for the Sphinx extension I had to write a while back.