Do not include HTTP examples using data_files anymore.

[lukasgraf]

This is a follow up to #568 - including the HTTP example files in data_files was a misguided approach. It sort of worked using buildout / easy_install, where those files got installed into the .egg (apparently this is a setuptools bug).

However, using pip, they get installed to the project root (sys.prefix) as specified by the setuptools documentation. This was undesired, and can lead to permission issues during deployment, for example in Docker images.

---

This change should hopefully fix this: It moves the HTTP example .json files inside the Python package plone.restapi.tests (in a subdirectory http-examples, which doesn't have to be a Python package itself)

• that way, they can be treated as first-class package data
• because MANIFEST already includes graft src/plone/restapi, we don't even need to list them in package_data, they should get picked up and bundled automatically during release
• These files can now be properly referenced using pkg_resources.resource_filename

Tested locally using:

• buildout
• pip

Tests pass, test_documentation properly updates the files, Sphinx docs build correctly, the .egg created via pip install correctly contains the files inside the egg, and the test-no-uncommitted-docs-changes-test still works.

Fixes #572

[sunew]

@lukasgraf looks good!
Why not copy the files over to the docs folder during the build of the documentation? (Or similar approach, perhaps generate during build of the docs)
It could be good if the docs (and the genartion of the docs) were independent of the tests being run.

[lukasgraf]

@sunew we could - but what exactly would we gain from that?

I see two possible scenarios when building the docs:

• examples are up to date (tests have been run)
• examples are out of date

The outcome is exactly the same for both those cases, irrespective of whether we introduce an additional copy-when-building-docs step or not.

Or in other words: Building the docs is independent of running the tests. Just building up-to-date-docs isn't. But it isn't either if we introduce a copy-when-building-docs step - if you want up to date docs, you'd still have to run the tests for the copy-step to pick up the new artifacts.

The downside is, for every change there's now to redundant sets of files to check in and to maintain, instead of a canonical source of truth.