search

Azure / azureml-sdk-for-r

Azure Machine Learning SDK for R
https://azure.github.io/azureml-sdk-for-r/
Other
104 stars 40 forks source link

Add "See Also" links to help pages #224

Open revodavid opened 4 years ago

revodavid commented 4 years ago

None of the function help pages in the azuremlsdk library include a See Also section. Including relevant functions in a See Also section would help users discover functions and navigate the help system better.

Describe the solution you'd like Add a see also section to the help pages listing relevant functions. For example, upload_files_to_datastore should refer to download_from_datastore and vice versa.

Additional context A "See Also" section is standard for R help files, and the R system makes referenced functions clickable links in help pages. You just need to provide function names, not URLs or file paths.

diondrapeck commented 4 years ago

Hi David - thanks for this suggestion. Some functions do have the "see also" section, but it would be great to make that more consistent across the documentation. Also, the existing "see also" section functions aren't clickable, so that bug will need to be fixed. I'll close this issue once those changes are made.

mx-iao commented 4 years ago

@diondrapeck do you know why the @seealso methods are not linking properly? When I run pkgdown::build_site() on my own machine to preview the site the linking works.

diondrapeck commented 4 years ago

Same here - I'll be investigating. It's probably something in this file.

mx-iao commented 4 years ago

@diondrapeck looking at some other packages, looks like in order to link properly you have to use this syntax [my_function()] rather than my_function(). Opened up a PR on workspace.R to validate.

diondrapeck commented 4 years ago

@mx-iao Links still aren't working on the site. Even with the new linking syntax. e.g. https://azure.github.io/azureml-sdk-for-r/reference/register_model.html

mx-iao commented 4 years ago

@diondrapeck looks like we might need to do: [azuremlsdk::my_function()]. Let me try that with my workspace PR. btw, what version of roxygen2 are we using for our docs pipeline?

Edit: actually we are using the same syntax as dplyr, which is working for them: https://github.com/tidyverse/dplyr/blob/master/R/coalesce.R