testcontainers-dotnet

testcontainers-dotnet copied to clipboard

Are there any frameworks or techniques for good documentation? Maybe something like AsciiDoc or GitHub Wiki?

Closed for inactivity.

@HofmeisterAn I'd love to help with this. It took me a while to figure out how to do certain things with the API, like changing the version of a specific database preset. I think simple API documentation would help tremendously!

OC, do you have anything specific in mind? Should we use the GitHub Wiki?

Good question. To be honest, I don't have a lot of experience with documenting a project like this, so I'm not really sure about what would be helpful. I think the Wiki would be a great place to house some kind of user guide, kind of like the readme now but a bit more extensive.

I also noticed this project uses XML documentation, so maybe that can be leveraged for the API documentation. I've found tools like Doxygen that promise to export these comments into readable documentation. Maybe the documentation on the Wiki could then reference parts of this documentation so people can see more about the API?

Also, there are plenty of tools that can convert markdown docs into a documentation website that can be hosted on GitHub Pages (like docsify and MkDocs). But I do not really see the advantage of that over using the wiki.

I think something like a "Get started" (Markdown) incl. more information, snippets, and examples in the XML documentation would be a good start. If possible, a combination of the Markdown and the generated API documentation.

@HofmeisterAn Alright, I started messing around a bit with scaffolding the API docs. I first tried out Doxygen, this worked pretty well but looks rather dated. It does seem to pick up all XML documentation correctly though. The CLI worked for me without issue, and there appears to be a GitHub action so the docs can be automatically re-generated whenever the branch updates. You can check out the generated html files in my fork (https://github.com/ysbakker/testcontainers-dotnet/tree/develop/html).

I also stumbled upon a different documentation generator named DocFX, this one is specifically meant for generating documentation for .NET projects. In my opinion, this one looks a bit more promising as it also allows custom pages and overrides / additions to the generated documentation. This might be more future-proof in that regard. Getting it to work was a bit more involved for me, but I use an M1 macbook and the tool doesn't support that architecture, so it shouldn't be an issue for most people. I experimented a bit with a pipeline (using mainly this tutorial) and got it to automatically deploy to github pages. You can check it out here: https://ysbakker.github.io/testcontainers-dotnet/docfx/api/DotNet.Testcontainers.Images.IDockerImage.html

The documentation is meant to mimic the Microsoft docs, which looks great in my opinion. Let me know what you think!

I experimented a bit with a pipeline (using mainly this tutorial) and got it to automatically deploy to github pages. You can check it out here: https://ysbakker.github.io/testcontainers-dotnet/docfx/api/DotNet.Testcontainers.Images.IDockerImage.html

Looks great! I think if we can add Markdown documentations (like code examples, etc.) too, this looks promising. That should not be a problem as far as I know, right?

Then we just need some storage to host the static HTML. I would like to avoid storing it in the Git repository. But I can take care of that.

I experimented a bit with a pipeline (using mainly this tutorial) and got it to automatically deploy to github pages. You can check it out here: https://ysbakker.github.io/testcontainers-dotnet/docfx/api/DotNet.Testcontainers.Images.IDockerImage.html

Looks great! I think if we can add Markdown documentations (like code examples, etc.) too, this looks promising. That should not be a problem as far as I know, right?

Then we just need some storage to host the static HTML. I would like to avoid storing it in the Git repository. But I can take care of that.

Yeah I'll look into customizing the documentation some more.

The appeal of the GitHub actions + pages approach is the simplicity (and the fact that it's free!) in my opinion. If you look at my fork, the HTML is only stored in a separate branch (which can be customized): https://github.com/ysbakker/testcontainers-dotnet/tree/gh-pages. Of course, it's up to you 😄

EDIT: The html in my fork is the generated content from Doxygen, I understand the confusion. My fork is kind of a mess haha. The only thing that would get added to the main repo is the docfx.json config file, a workflow file and maybe the markdown documentation. At least, I assume you do want the markdown documentation in the main repository? Or should this be a separate repository?

Testcontainers Java and Testcontainers Go try to follow the same documentation approach and styling: https://www.testcontainers.org/ https://golang.testcontainers.org/

We should try to achieve consistency across the Testcontainers ecosystem, regarding the style, but maybe also how we technically do it. But it is something we can sync up on in more detail in the future. I would definitely suggest that we don't go with a unique approach for .Net for now.

Testcontainers Java and Testcontainers Go try to follow the same documentation approach and styling: https://www.testcontainers.org/ https://golang.testcontainers.org/

We should try to achieve consistency across the Testcontainers ecosystem, regarding the style, but maybe also how we technically do it. But it is something we can sync up on in more detail in the future. I would definitely suggest that we don't go with a unique approach for .Net for now.

I see, that would make sense. Would you agree that having a separate space for the API documentation is still useful? Especially with the way that almost all methods and classes in the .NET project already have XML documentation, I'd say it's a waste to not use it to scaffold API docs. In my opinion, the API documentation and "usage oriented" documentation can be completely separate as well.

So in that case this project would use docFX to scaffold the API documentation, and perhaps Mkdocs (with the material theme, which both the projects you mentioned seem to use) can be used to generate the other documentation? That way, the "main" documentation is consistent with the other projects, but can contain references to the API documentation that is more specific to the .NET project.

I think an API documentation incl. more information about how to use or work with testcontainers-dotnet is very helpful. Especially as long as the API is different (refactoring the API will take some time). It helps developers to write their first tests quicker, without common mistakes, etc. Furthermore, the documentation can assist the migration to the "new" API in the future.

An equivalent to https://golang.testcontainers.org/ would be perfect. DocFX will generate in addition something like GoDoc.

@kiview I assume we publish the documentation via Netlify too?

@HofmeisterAn Indeed, for now the docs in tc-go and tc-java are published with the same mechanisms and by using Netlify for building/hosting the site. While we eventually might explore options for a more centralized entrypoint into the documentation, a first step for tc-dotnet could be replicating the Go and Java approach and hosting the docs at dotnet.testcontainers.org.

I would be glad to bootstrap the mkdocs site, is there also a way to make the main site more into a broad overview side with short links to the other documentation pages? As of now its pretty confusing to click on the link in this repo and then seeing the testcontainers-java site.

Just today we setup https://dotnet.testcontainers.org/ 😀 (it is part of docs/32-prepare-documentation and WIP).

make the main site more into a broad overview side with short links to the other documentation pages?

We are discussing right now how to organize the different languages more structured. This will take some time. In the meantime, I will continue to improve the .NET documentation. I would be happy about any ideas or suggestions on how to organize it.

whoops than I invested a view minutes setting it up in vain. But nice to see some work there. (I was about to open a PR)

BTW: It might be good to also have a look at the different branch names in all the projects. This project is using develop as a default while the others use main. This leads to people wanting to edit the doc sites running into 404s. (Maybe you can already open a draft PR than I can add a comment like in the other repos to fix the link (e.g. https://github.com/testcontainers/testcontainers-go/pull/575/files)

whoops than I invested a view minutes setting it up in vain. But nice to see some work there. (I was about to open a PR)

Sorry for that. I like the idea with the examples 👍 .

Maybe you can already open a draft PR than I can add a comment like in the other repos to fix the link (e.g. https://github.com/testcontainers/testcontainers-go/pull/575/files)

OC, I will create one tomorrow morning.

Thanks! Regarding the central documentation site I found this: https://github.com/backstage/mkdocs-monorepo-plugin

Which might be a solution to the problem and makes for less reconfiguration in each repository.