Libdoc's DocumentationBuilder doesn't anymore work with resource files with .robot extension

[pekkaklarck]

When support for generating documentation for suite files was added (#4493), the DocumentationBuilder factory method was changed so that it returns a SuiteDocBuilder with all files having a .robot extension. This builder only works with suite files and not with resource files. The LibraryDocumentation factory method that uses DocumentationBuilder handles this problem internally similarly as it handles DocumentationBuilder not supporting resource files in PYTHONPATH so this doesn't affect Libdoc itself. It does, however, affect direct usage of DocumentationBuilder.

Changes like this are always annoying, but in this case this isn't too severe because DocumentationBuilder isn't really part of the public API and LibraryDocumentation should be used instead of it. Alternatively, it's possible to use ResourceDocBuilder explicitly when working with resource files. The initial plan was to just document this behavior (#4517), but it is actually easy to fix this by making DocumentationBuilder a class instead of a factory method.

A related problem is that Libdoc's public API isn't properly defined. A separate issue needs to be submitted about that. We can then explicitly recommend LibraryDocumentation.