databrickslabs
Documentation headings
It looks like the code generator is converting headings to:
#' **Release status**
Instead of
## Release status
Additionally, in statement_execution.R it's generating this:
#' ----
#'
#' ### **Warning: We recommend you protect the URLs in the EXTERNAL_LINKS.**
#'
#' When using the EXTERNAL_LINKS disposition, a short-lived pre-signed URL is
#' generated, which the client can use to download the result chunk directly
#' from cloud storage. As the short-lived credential is embedded in a pre-signed
#' URL, this URL should be protected.
#'
#' Since pre-signed URLs are generated with embedded temporary credentials, you
#' need to remove the authorization header from the fetch requests.
#'
#' ----
#'
and the sequences of dashes are causing this warning when documenting:
Warning: [statement_execution.R:12] @details markdown
translation failed
✖ Internal error: unknown xml node thematic_break
ℹ Please file an issue at
https://github.com/r-lib/roxygen2/issues
If you can tell me what you're trying to achieve here, I can suggest how you might best express that in R's documentation.
The source text is written in markdown (see this page for another render), converted by https://github.com/databricks/databricks-sdk-go/blob/main/openapi/code/named.go#L251-L310, resulting in the comment renders.
If you could provide a set of markdwon-to-rdoc rules, would be great. if it's a PR to generator - even better.
Ah, if the source doesn't use headings, there's little point in patching up the markdown here. Let me contemplate the thematic_break a little more; maybe it's easier to handle in roxygen2 since all the docs are auto-generated here. (I'm actually impressed that roxygen2 already handles all the markdown you supply 😄)
@hadley technically we can do special comment preprocessor in the generator. up to you :)
@hadley so, is there anything we need to do with markdown to turn it more roxygen friendly?
Probably the easiest solution would be just to strip the lines that consist of only --- in the preprocessor.