Document that Libdoc's DocumentationBuilder expects .robot files to be suite files, not resource files

[pekkaklarck]

RF 6.0 made is possible to generate keyword documentation for suite files, not only libraries and resource files (#4493). As the result Libdoc's DocumentationBuilder factory method nowadays returns SuiteDocBuilder, not ResourceDocBuillder, for all files with the .robot extension. This causes problems with resource files having .robot extension because SuiteDocBuilder only works with suite files.

We have few different approaches how to handle this change:

1. Enhance DocumentationBuilder so that it would actually parse .robot files to see are they suite or resource files instead of only looking at the extension. This would basically mean we always parse these files twice, but I doubt it would have a significant performance penalty. The main reason I don't like this too much is that the factory method already earlier didn't handle resource files that are imported from PYTHONPATH correctly and that special case needs to be anyway handled later.
2. Enhance SuiteDocBuilder so that it works also with resource files. Feels a bit strange for me.
3. Just document this behavior and instruct users to use ResourceDocBuilder explicitly with resource files.

My current thinking is that option 3. is adequate even though it doesn't actually fix the issue. This is why I believe so:

1. You should in general use the LibraryDocumentation factory method instead of DocumentationBuilder. The former method uses the latter and handles different special cases like a resource file with the .robot extension.
2. Resource files should in general use the .resource extension instead of .robot.
3. If you know you are working with resource files, you can easily use ResourceDocBuilder explicitly.
4. The change happened in a major version.

Let me know in the comments if you have concrete needs to use DocumentationBuilder directly that would benefit from it handling .robot files better.

[pekkaklarck]

Turned out it's so easy to fix DocumentationBuillder (#4519) that let's do that instead. Need to also document Libdoc's public API better and mention that LibraryDocumentation is the preferred API to use (#4520).