Docs improvements #95
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
rwb27
force-pushed
the
docs_improvements
branch
2 times, most recently
from
8228b9a to
4b3a8fd
Compare
Barecheck - Code coverage reportTotal: 81.6%Your code coverage diff: 0.05% ▴ ✅ All code changes are covered |
The quickstart page was badly out of date. I've updated it to reflect changes in the package, and in how the labthings server is started.
This checks that the server code in the quickstart page actually runs. It tests for successful server start-up, using the same code as test_server_cli.py. This does not verify that the HTTP server actually works - but it should catch obvious errors in the example.
I've also added a test for the example in here.
This is not yet run in CI, but should check the example.
rwb27
force-pushed
the
docs_improvements
branch
from
2510577 to
963cd23
Compare
I fixed a few path gotchas and added the test so it runs with unpinned dependencies.
rwb27
force-pushed
the
docs_improvements
branch
from
963cd23 to
eba356c
Compare
|
I've only added the installation script test to the unpinned dependency test job. This is because the example script doesn't pin dependencies either - so it's vulnerable to things changing. As with the unpinned test job, I think it's best to allow merging PRs where it fails because of changes to dependencies, but to ensure it's passing before releases. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR addresses some of the issues in #94 by updating the quick-start page, and adding a unit test for the example code there. It doesn't test installation of the package from pypi, but does test that the example code runs.
I have also updated the page on dependencies, and added a unit test for the example code there.
The need for a server means example code is often not entirely straightforward to test - for the quickstart example, I use a subprocess, and monitor its output to check a FastAPI server starts. This is not particularly quick or elegant, but it seems fairly robust. The test for the dependency example uses a TestClient, which is an efficient mechanism provided by FastAPI to allow the server to be used without actually serving over the network. It's much faster, but results in some boilerplate code that's best not included in the examples viewable in the docs. This suggests that it might be quite hard to get something like
doctestto work nicely.I think properly testing the quickstart example would be really useful - but might require a bit of a rethink of the CI pipelines to work nicely.