search

lsms-worldbank / adodownr

⏬ Create Quarto package documentation website for Stata packages
Other
6 stars 1 forks source link

Make logo optional #6

Closed kbjarkefur closed 10 months ago

kbjarkefur commented 1 year ago

Logos are nice and we should keep them. However, we should make it optional and have a default behavior when this file does not exists.

https://github.com/arthur-shaw/adodown/blob/6d5ed941202c274248a3ffcd9f484a80593a85cb/R/build.R#L204-L208

Also, since we have an opinionated folder structure, I think our instructions for how to use the adodown workflow will be more concise if we have a specific location for this file. That specific location should be the same location where we eventually will allow custom themes etc. to be stored.

Would the src/dev/ folder be a good location for this?

Also, if I understand correctly fs::dir_ls makes find_file_in_pkg() return a list/vector of file locations in case multiple files match that pattern.

https://github.com/arthur-shaw/adodown/blob/6d5ed941202c274248a3ffcd9f484a80593a85cb/R/metadata.R#L1-L14

This becomes and issue when the logo is copied to the output location here:

https://github.com/arthur-shaw/adodown/blob/6d5ed941202c274248a3ffcd9f484a80593a85cb/R/build.R#L209-L213

This might not be that likely in the case of logo.png but possible, but this caused an issue for me with .pkg files. See issue #5. I admit these are unlikely to cause error in most cases, but I think its more stable to have a specific location, and I'd suggest preferring that over being flexible with location of these files.

arthur-shaw commented 1 year ago

The quite like the idea of having a directory that contains optional assets for the Quarto site (e.g., image, CSS, SCSS, etc). What should we name it? I'm slightly partial to the generic names like assets or site.

kbjarkefur commented 1 year ago

Of those options, I prefer assets as those files are assets used for the site and not the site itself. I think a folder called site might lead people think they should expect to find the built site there. The built site should only be in the gh-pages folder if using our standard workflow. Someone not using our workflow will need to set up their own site folder for the built site. That folder might be on a server or something and might not be in the clone, I'd say we should not create a folder for that less common use case.

Where should this folder be created? I'm concerned that a folder called assets in located in the src folder would be expected to have assets used by the commands and not used by some tool that build web documentation. What about creating a folder next to src at the root of the package folder called site-assets?