lsms-worldbank / adodownr Goto Github PK

adodown no longer has a name field in the pkg file. The name needs to be extracted from elsewhere. See this conversation.

Since the custom reference index is manually composed, users can easily make typing or copy/paste mistakes.

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.

The file could be missing or could be named incorrectly.

When setting up a new adodown project with the Stata command ad_setup, this file src/mdhlp/README.md is created with instructions about the mdhlp folder.

When building the site using adodownr that README should not be included.

Here is where I think all .md files in src/mdhlp/ is listed:

And here is the definition of the function that is used. I guess this function should allow for a parameter that is a list of file names to skip:

This is not urgent as the work-around is to delete the file src/mdhlp/README.md. But that's not a great long term solution.

find_file_in_pkg() returns a list/vector of files that match the file pattern if more than one file match that pattern.

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

This part of the code search the repo for all files with file extension .pkg. That means that a list/vector of file will be passed to get_pkg_metadata() if multiple files with that file extension exists.

https://github.com/arthur-shaw/adodown/blob/6d5ed941202c274248a3ffcd9f484a80593a85cb/R/initialize.R#L36-L41

Passing a list/vector of files will create an error here:

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

Since we know the .pkg file will be located in /src/ (see https://github.com/lsms-worldbank/adodown/blob/main/src/adodown.pkg), I think we should look for the file only there.

However, this file will have different names depending on what the package name is so it might be difficult to make this completely error proof. I can't think of a better way to solve this than to list all files in the /src/ folder with format .pkg and throw a helpful error if that folder does not contain exactly one file with that pattern. That error message will show in the Actions log. Which not everyone will be able to find, but I think that is the best we can do.

I admit this wont be a common error, but I ran into it when I tried to set this up for https://github.com/lsms-worldbank/adodown as the template folder has this template package file: https://github.com/lsms-worldbank/adodown/blob/main/src/ado/templates/ad-package.pkg.

After #7 is merged, I get the error below in this GHA-job in for repo labeller

Error: Error: [ENOENT] Failed to copy '/home/runner/work/labeller/labeller/README.md' to '/home/runner/work/labeller/labeller/index.qmd': no such file or directory

Does this error message make sense to you @arthur-shaw ? I wonder if the duplicated labeller/labeller can be the error?

Currently, when md files are transformed into qmd files, the file name is taken as the title if no title is provided in the md file's YAML (or if no YAML exists). This results in awkward titles (e.g., mycommand.md)

Instead, compose the title from the file name minus the extension (e.g., mycommand.md -> title: mycommand). This is a reasonable choice since files typically bear the name of the command they contain.

For currently unknown reasons, the _quarto.yml file is written with / as the first line. To combat that, adodown deletes that line. But it would be better if that line weren't written in the first place.

More generally, exclude a link in the navbar if "child" elements are not present in the package. The most likely visible case will be for vignettes/articles, which Stata users arent' apt to write and Kristoffer and I haven't yet written for labeller and selector (since these are often the last pieces of documentation).

If an image appears in the main README of an adodown repo, it lives in src/dev/images/. When that README is converted to a qmd file in order to build the site's index page, the path needs to change to images/. This path conversion needs to be integrated into the build process.

Currently, adodownr looks for a title in YAML. If it exists, it uses that as title. If it doesn't exist, it takes the file name as title.

For the adodown documentation, article titles appear as h1 headers (ie, come after #). That generates strange articles that have two titles (h1 headings): name of the file, since no title was found with current heuristics; h1 heading that already exists in the article.

Should we take the first h1 heading as the title?

This folder is optional. The program should not expect it in order to build the site.

This regression probably comes from #24 .

To my mind, this entails:

• Syntax highlighting
• Styling that makes code block look like Stata console/dofile editor

This might translate into a few tasks

• Mark code blocks as Stata--ideally when writing from md to qmd. See Quarto docs here.
• Apply a Stata-looking style. Either adopting a built-in style that's close or rolling our own. See Quarto docs here

The build_reference_index() function currently builds an index page/table that's an alphabetically arranged list of commands present in the package.

While this is definitely much better than nothing, it would be far better if the list could be ordered and/or grouped by the package author.

To help users undertand the scope of the package and find the right commands for the right job, the author might want to organize commands by theme or by function. For example, labeller has commands for variable labels and value labels. It would be good to group them in this way.

For inspiration, see pkgdown's YAML specification for custom index pages. See also a worked example for susoapi: YAML file here; resulting page here.

When building the site, see warning in the logs:

WARNING: Unable to resolve link target: articles/README.qmd
Output created: docs\index.html

Terminating existing preview server....DONE

Preparing to preview
[1/6] articles\topic1.qmd
WARNING: Unable to resolve link target: articles/README.qmd
[2/6] articles\topic2.qmd
WARNING: Unable to resolve link target: articles/README.qmd
[3/6] news.qmd
WARNING: Unable to resolve link target: articles/README.qmd
[4/6] reference\command1.qmd
WARNING: Unable to resolve link target: articles/README.qmd
[5/6] reference\command2.qmd
WARNING: Unable to resolve link target: articles/README.qmd
[6/6] reference\index.qmd
WARNING: Unable to resolve link target: articles/README.qmd

Watching files for changes
Browse at http://localhost:6350/
Stop the preview with quarto_preview_stop()Browsing http://localhost:6350