Develop Reference

customising pdoc automatically generated documentation for python

I used pdoc3 to automatically generate documentation from the docstrings at the beginning of each python class/function by executing the following
pdoc3 --html ambit_stochastics
The resulting documentation can be found at https://danleonte.github.io/Ambit_Stochastics/index.html
Can I remove the ambit_stochastics from ambit_stochastics.helpers on the index page and, subsequently, on all of the subpages? It seems unnecessary and wordy.
Can I edit the index page ( the one that pops up when accessing the link) to add some introductory text? how about other templates?

Not sure about your #1 point without editing the template, but you can tackle #2 by including a module docstring in your ambit_stochastics/__init__.py like pdoc does. This ten renders on the main module page, along with its TOC for titles:
https://pdoc3.github.io/pdoc/doc/pdoc/

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?

have sphinx report broken links

When building html documentation, how do you force sphinx to report, or create an error, on links that don't exist?
Specifically, I have properties and methods within my Python project that have been removed or renamed, and it is hard to find all the dead links with the sphinx generated html output.
I feel like I'm staring at the answer here:
http://sphinx-doc.org/glossary.html, as descriped in the opening paragraph.
I'm obviously not understanding something.

Set the nitpicky configuration variable to True (you can also use the -n option when running sphinx-build).
In nitpicky mode, a cross-reference to a function (such as :func:`myfunc`), class, or other object that cannot be found will generate a warning message.

I think CheckExternalLinksBuilder is what you're looking for.
It's basically used by calling 'sphinx-build' with -b linkcheck option. Please see sphinx-build for more info. Also, take a look at the list of sphinx-extensions here and here.

Pygments to latex better formatting for py code

I am trying to include python code in my lyx document by inserting a file. I began by trying to use listings but this was causing code to overflow pages.
Now I'm using pygments setting it up as described in this tutorial, http://wiki.lyx.org/Examples/IncludeExternalProgramListingUsingPygments. This appears to work fairly well but the code highlighting is off. for instance def and elif keywords are not highlighted and docstrings do not highlight if they are split over multiple lines.
I have tried changing the style to a few different built in ones but this hasn't worked.
Has anyone got a/ knows of a good way to highlight python code in the same way as idle does.
Thanks.

You should check out package called minted, although I don't know how well it works together with Lyx. But in regular latex file you can just do:
\usepackage{minted}
...
\inputminted[]{python}{python_file.py}

Search function with PyGTKsourceview

I'm writing a small html editor in python mostly for personal use and have integrated a gtksourceview2 object into my Python code. All the mayor functions seem to work more or less, but I'm having trouble getting a search function to work. Obvioiusly the GUI work is already done, but I can't figure out how to somehow buildin methods of the GTKsourceview.Buffer object (http://www.gnome.org/~gianmt/pygtksourceview2/class-gtksourcebuffer2.html) to actually search through the text in it.
Does anybody have a suggestion? I find the documentation not very verbose and can't really find a working example on the web.
Thanks in advance.

The reference for the C API can probably be helpful, including this chapter that I found "Searching in a GtkSourceBuffer".
As is the reference for the superclass gtk.TextBuffer

Here is the python doc, I couldn't find any up-to-date documentation so I stuffed it in my dropbox. Here is the link. What you want to look at is at is the gtk.iter_forward_search and gtk.iter_backward_search functions.