[Documentation]: The docs don't always prepend the package to types #2180
Comments
mdelapenya
added
documentation
|
Thanks for opening this issue, but I'm afraid it will not be as easy: the docs site is able to embed files from the source code, and we do have two types of test files where to grab those code snippets:
I'd be more than happy with having more hands rewriting all test files with this "_test" pattern 😄 As a direct consequence, all code snippets that are embedded from the test files will automatically receive the update. |
|
I'm more than open to make that PR if it'd help 🙂 Though, pure curiosity, would it be doable to potentially transform the generated docs HTML/content (not sure how the docs are generated, yet) once it has been generated? Maybe we could look at keeping a reference to all the structs from |
|
We currently use In the mean time, I'd go with the test packages. |
…mports As discussed in testcontainers#2180, the imported examples from tests for the docs from lack the package prefix before the imports, which leads to the example not being directly copy/paste-able. To solve the issue it was suggested to create a `testcontainers_test` package for the example tests and to convert everything. I did my best to convert all the tests in a way that makes sense, and I extracted any test that would import very internal things that we should not export. Some of the tests had to be slightly rewritten (the lifecycle tests in particular), but they should stay pretty much the same. Test by running all the root unit tests, they should all work as expected. The examples in the docs should all have the packages as prefixes now.
|
I started a PR with your suggested changes for the test packages, let me know if that's not what you had in mind 😄 |
This work has been extracted from testcontainers#2202 and is related to testcontainers#2180. See the original PR for the full context and reasoning.
This work has been extracted from testcontainers#2202 and is related to testcontainers#2180. See the original PR for the full context and reasoning. This will help with the documentation, since all examples will now have the module prefixes.
This work has been extracted from testcontainers#2202 and is related to testcontainers#2180. See the original PR for the full context and reasoning. This will help with the documentation, since all examples will now have the module prefixes.
This work has been extracted from testcontainers#2202 and is related to testcontainers#2180. See the original PR for the full context and reasoning. This will help with the documentation, since all examples will now have the module prefixes.
This work has been extracted from testcontainers#2202 and is related to testcontainers#2180. See the original PR for the full context and reasoning. This PR in particular moves all the simpler tests in one go, or adds a comment to any remaining tests that would not make sense to move (or could not be moved without exposing a lot of variables). This will help with the documentation, since all examples will now have the module prefixes.
Proposal
In the docs, many pages have code example you can copy, but those examples don't always contain the package that contains the structs used in the example as a prefix, this is the case for the Dockerfile docs, parts of the networking docs, and the files and mounts docs, to name a few.
This makes this code not directly usable when a user wants to try things out by first copy/pasting the example, then modifying once they see what happens. It's a minor thing, but
testcontainers.needs to be prefixed to every struct every time they copy something, which can lead to errors if they forget to do so.It'd be great if the docs could include these prefix on all structs, or possibly have the examples in context as a separate tab in the code blocks, so we can see the code used in a real test.
The text was updated successfully, but these errors were encountered: