Adds a detailed example for Quarto within Documenter.jl

[kellertuer]

This PR is an explanation for a detailed solution for #79. So this resolves #79.

Let me know whether this is maybe too detailed or how I can maybe improve this even further.

[cscheid]

Thanks for the PR and contribution. As I think about this, a Julia-specific example doesn't seem to fit with the other examples without a larger reorganization of the README.md page. This is especially true since the name example-09-render-to-documenter.md makes no reference to Julia, and .jl might not be enough of a clue for non-Julia users. I wonder how we should go about this. @cderv, what do you think?

[kellertuer]

No worries, I can also look for another place, where to leave/put this tutorial, but since it took me 2 weeks to figure this out (and even having the idea but no clue how to approach it several months ago), I thought it‘s worth to but it somewhere.

[cderv]

Thanks @kellertuer !

@cscheid I agree with you. This is a rather long and complete example, which is great ! The current example organization does not work great for this.

I would go with either:

• Maybe a sub-folder in examples to such complete examples ? Like examples/workflows and put inside it
• Move the existing examples .md in a docs/ folder as they are rather documentation of the actions really.
• Take this opportunity to move the quarto actions docs and examples into https://quarto.org

Is there anything that you find more adapted ? Do you have other example ?

[kellertuer]

No problem. If you have decided for a good way to go, I am happy to help to include this somewhere. I think it would be great to even have more examples that are a bit more complex.

[cscheid]

I would go with either:

• Maybe a sub-folder in examples to such complete examples ? Like examples/workflows and put inside it]

I like this.

• Move the existing examples .md in a docs/ folder as they are rather documentation of the actions really.

I like this too.

• Take this opportunity to move the quarto actions docs and examples into https://quarto.org

I don't like this, because it requires us to coordinate two sources of truth. (we have to remember to update the website if we change anything here, and vice-versa)

If anything, I think this makes me consider a whole quarto website with documentation and examples under quarto-dev.github.io/quarto-actions.

[kellertuer]

So which would now be the preferred way to move the files? For me points 1 and 2 (which I find both ok) are contradicting a bit. So what do we do

• All examples into docs ?
• all (old) examples into docs/examples and my new one into docs/workflows? (that would be a mix of the two proposed things)
• a folder examples/workflows for my complex idea?

[cscheid]

@kellertuer I'll discuss this with @cderv (we have a weekly group meeting) and I hope to get back to you in a couple of days.

[kellertuer]

I wrote a small forem post today

https://forem.julialang.org/kellertuer/render-quarto-tutorials-in-documenterjl-with-github-actions-3fo

but we can of course still add the example here as well if you like.

[kellertuer]

Shall we continue this at some point or should I close this PR?

[cscheid]

@kellertuer I did have a conversation with Christophe about this. We both agree that

• your example is useful
• the structure of our documentation page is not well-suited for your example

So we're left with needing a big restructuring of this documentation. Unfortunately I'm all booked with other work and Christophe is OOO. So it will be a while until we can get to this. But it's on our radar!

[kellertuer]

Ok, well. Then I will put this aside for now and wait for an update from your side.