Change autofile approach to predeclared file names

Prior to this commit we were attempting to implement the
auto-functionality by having placeholder custom docutils nodes which
stored the required code source files for use with doxygen. Then the
plan was to do a pass over all the nodes, figure out all the files we
needed to generate doxygen xml for, generate it and then go through and
replace all the placeholder nodes with actual doxygen documentation.

Unfortunately, Sphinx/docutils doesn't work like that. We can insert the
nodes but then all transformations to the first document and its nodes
have to be done before processing of the second document has begun. So
we can't collect information from all the documents and return to the
first document to transform/process it with our new found knowledge.

So, as we can't automatically collect the list of files to be
doxygen-processed from the rst files, we have to ask the users to
pre-declare them in the config.py so that we can do everything we need
before we start to process the documents.

This simplies things quite a bit and we can strip out all the custom
node and transform code we had and instead preprocess all the declared
files in the "builder-init" hook that Sphinx provides us.

When it comes to the directives, it is then just a case of figuring out
if we're a normal directive in which case we get our project_info from
the config or if we're an autodirective in which case we project_info is
determined by the preprocessing step.

I imagine the code could be a little better at this stage. In
particular, the management of the doxygen xml generation. We should be
storing some timestamps and file associations to have a better idea of
when to regenerate the xml.
Fix user documentation and add comments

We fix the documentation pages to refer to the new meanings and
behaviour of the auto directives and the breathe_projects_source config
value.

We also add some addition comments to the code in an attempt to clarify
some parts.