new documentation structure #240
Conversation
|
@sv3ndk thank you so much! I'll give it a look this week! |
project/metals.sbt
Outdated
| @@ -0,0 +1,6 @@ | |||
| // DO NOT EDIT! This file is auto-generated. | |||
There was a problem hiding this comment.
Is this file committed intentionally?
There was a problem hiding this comment.
good catch! Indeed I put it there by mistake, I'll remove it
docs/src/main/tut/usage.md
Outdated
|
|
||
| Since this project is essentially a scala wrapper, please familiarize yourself with the [Testcontainer documentation](https://www.testcontainers.org/) first. | ||
|
|
||
| This section describes the syntax valid since version 0.34.0. See this [pull request](https://github.com/testcontainers/testcontainers-scala/pull/78) for the motivation of the change. The legacy API description is [available here](usage_legacy.md). |
There was a problem hiding this comment.
Can we make "The legacy API description is [available here]" bold? So people can find more quicker
README.md
Outdated
| @@ -10,976 +10,22 @@ allows using docker containers for functional/integration/~~unit~~ testing. | |||
|
|
|||
| > TestContainers is a Java 8 library that supports JUnit tests, providing lightweight, throwaway instances of common databases, Selenium web browsers, or anything else that can run in a Docker container. | |||
|
|
|||
| [testcontainers-scala in action](http://dimafeng.com/2016/08/01/testcontainers-selenium) | |||
| The following test frameworks are supported: | |||
There was a problem hiding this comment.
Curious if it'd make sense to move this to the usage doc or to the bottom of this doc
There was a problem hiding this comment.
My motivation for including it in the front page was that it's likely the first question a newcomer would ask: is this relevant for me, does it support my test framework?
I'll move it down the doc and you'll let me know what you think
README.md
Outdated
| - [Currently,](https://github.com/scalameta/munit/issues/119) there is no way to retrieve test status in MUnit `afterEach` block, so `afterTest` hook will never contain an error. | ||
|
|
||
| If you have any questions or difficulties feel free to ask it in our [slack channel](https://testcontainers.slack.com/messages/CAFK4GL85). | ||
| * [technical guide](docs/src/main/tut/index.md) |
There was a problem hiding this comment.
I think it'd be a bit more discoverable if we move usage one level up and separate docs and the article. Something like this:
Documentation
Links
There was a problem hiding this comment.
Good idea, I'll do that. I will be simpler too
Hi,
As promised in #239, here is a proposition that revisits Testcontainer-scala documentation.
I took the initiative to change the structure quite a bit, although I'm of course totally fine if you would like to take another approach, just let me know what you prefer and I'll adapt.
You can browse the result directly from my branch: https://github.com/sv3ndk/testcontainers-scala/tree/239_update_documentation
Overview:
I split the content in multiple files, s.t. the readme now only contains some high level info, then links to the technical guide and the release notes
I put the technical guide in the
doc/folder. I understand this was supposed to be used for a microsite, although it does not seem to be used atm, and it's always possible to upgrade the whole thing to microsite format laterthe setup and API usage are now in separate pages. My reasoning is that users will likely read the setup only during their first visit, then want to skip directly to the API usage any time they come back to the doc
In the setup, I recommended to use sbt
IntegrationTestinstead ofTestconfiguration , is that ok with you?The technical guide now first and formost presents the new API, although the legacy documentation is still reachable in a separate link
I included the imports in the code examples
I kept only one full example with both Scalatest and MUnit, after which point I'm assuming it's clear to the reader how to adapt the code, s.t. I've only shown Scalatest examples after that. The specificities of MUnit fixtures are still mentioned at the end of the document
I do realize there's quite some change up there, so of course don't hesitate to let me know if you would like a different structure.