Added autodoxygenfile directive help

To help with testing.
Extracted all {Auto,}DoxygenIndex related code

To an index.py file as it is scattered between the directives, nodes and
transforms otherwise (which is a reasonable division but turns out to be
harder when working on a particular code path, better to have all index
stuff together, then all file/class/function stuff together when it
comes.)

We have to create a base.py as well and move the base classes from
directives.py into that to avoid circular imports.
Separate ProjectInfo code to project.py

It is a large enough chunk of code to warrant it and it needs to
available for import into other files which is hard from the central
directives.py without circular imports.

We also fix up the missing imports and names in base.py
Clean up imports in directives.py
Support autodoxygenfile directive

The initial index.py refactoring was based on the assumption that we
couldn't share a lot of the node and transform code. It feels like we
can for the moment so we've moved some of the index.py code back into
more generic locations and names in transforms.py, nodes.py and base.py.

We then introduce file.py with the necessary directives and FileHandler
to do all the file specific work and then we adjust the transforms to
handle the Handlers and their data more generically.

The FileHanlder ends up being a cut-paste-and-tweak of the original
DoxygenFileDirective code which is promising for future changes.
Rename Handler to NodeHanlder to be more specific

Else it is super generic.

Also relocate the NodeHandlerFactory to a more reasonable spot.
Fix pyflakes errors

We should have some kind of pre-push hook or general build check for
this stuff.
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.
Flake8 fixes and reformatting
Merge branch 'autofile'