quarto-dev / quarto-dev/quarto-cli
Document in more places that `output-dir` will be deleted
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 6k
- Forks
- 458
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 41
Description
The output directory is (usually) completely deleted (see eg #13623). In the related issue #13892, @mcanouil said
See
quarto render --help.
However, quarto render --help does not actually say anything about this rather important point. Currently, this is what it says:
--output-dir - Write output to DIR (path is input/project relative)
and I propose changing this to, perhaps:
--output-dir - Write output to DIR, which is first deleted if it exists (path is input/project relative)
This misses some subtlety, of course.
I'm currently trying to find where in the docs it actually says that the directory will be deleted. I'm sure it says it somewhere, but it's a bit hard to find. I would suggest adding this VERY IMPORTANT caveat to all the places it discusses output-dir.
For instance, on project options:
Same thing on project options for websites:
Similarly, this fact is not mentioned on the Output Path section for books.
Tangentially, this is not mentioned either in at least this place in TPG.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with quarto render --help and the linked project options, website project options, book output path, and TPG project options pages to locate every output-dir description. Update the relevant documentation and help text so the deletion caveat is stated wherever output-dir is discussed, then verify the rendered pages and help output.
Written by the indexing model from the issue text.
Assessment
- Domain
- cli, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100