Add more documentation

[annakrystalli]

This PR adds:

• A vignette about validating PRs on GitHub targeted towards hub administrators including details of individual checks.
• A vignette on validating submissions locally targeted towards teams including details of individual checks.
• A vignette containing more details on the structure of objects returned by validation functions and how to access more information about individual check objects.
• A csv detailing all the checks performed across the validation family of functions.

Also intend to add:

• Add details of model metadata checks to the csv
• Make appropriate subset of details contained in the csv available in lower level individual function roxygen documentation, e.g. validate_model_data, validate_model_file, validate_model_metadata.
• Link (segway) vignettes to each other
• Update NEWS.md including bug fix

To test out, chek out branch locally, install with devtools::install() and build site with pkgdown::build_site().

Docs Preview up here! https://659ebe799507d50a38fa6df3--hubverse-pkgdown-preview.netlify.app/articles/hub-validations-class

[nickreich]

1. I note that some actions can be turned off when PRs are coming in to clones of the repo. Is this something that we can/should discuss in one of the articles briefly, maybe validate-pr? Noting that I filed a relevant issue over here.
2. The validate-pr vignette seems good as is, and I think is acceptable. That said, I do think that having some additional content about what the output actually looks like ON GITHUB would be a valuable addition to the vignette. It feels very abstract and "command-line centric" right now, when the advantage of having this set-up is so that we can take advantage of all the nice GUI stuff that comes along with having it run on GitHub Actions. And for a reader who is looking for something about "what will this look like for a modeler end-user" I think this vignette doesn't quite answer that currently. Noting that I think we could merge this PR as is and file a new issue to update the vignette with more of these details/images/links to failing or passing PRs etc...
3. Is there documentation somewhere for developers that makes it clear that if new canonical validations are added to this package that they should also be added to check_table.csv?

[github-actions]

🚀 Deployed on https://65aab8b6f8a51111621752ed--hubverse-pkgdown-preview.netlify.app

[annakrystalli]

1. I note that some actions can be turned off when PRs are coming in to clones of the repo. Is this something that we can/should discuss in one of the articles briefly, maybe validate-pr? Noting that I filed a relevant issue over here.

Thanks for the issue! Answered there!

2. The validate-pr vignette seems good as is, and I think is acceptable. That said, I do think that having some additional content about what the output actually looks like ON GITHUB would be a valuable addition to the vignette. It feels very abstract and "command-line centric" right now, when the advantage of having this set-up is so that we can take advantage of all the nice GUI stuff that comes along with having it run on GitHub Actions. And for a reader who is looking for something about "what will this look like for a modeler end-user" I think this vignette doesn't quite answer that currently. Noting that I think we could merge this PR as is and file a new issue to update the vignette with more of these details/images/links to failing or passing PRs etc...

While I can appreciate that some screenshots on GitHub could be useful I generally try to avoid screenshots of code in documentation because they are more cumbersome and time consuming to update (whereas any changes to the output of code will update automatically when rebuilding the site).

Ultimately what we get in the GitHub Action is output on a command line so it will not differ to what is shown in the vignette. Of course, they will need to have some familiarity with GitHub Actions to know where to look for the output and I think this is really where you feel a screenshot would be a useful addition which I do agree with so I've added a single example screenshot to orient folks.

Having said all this, once hubverse-org/hubverse-actions#3 is complete, it's likely that results will be reported as a PR comment as standard. I'll make a note in that issue to ensure documentation is updated accordingly when it's complete.

3. Is there documentation somewhere for developers that makes it clear that if new canonical validations are added to this package that they should also be added to check_table.csv?

I'll add something now

[annakrystalli]

OK! I've now added a note about updating inst/check_table.csv with metadata about the check. Hopefully all your concerns jave been addressed @nickreich ?

[annakrystalli]

I'll wait till @LucieContamin has had a look before merging though. See link above for rendered preview of docs

[nickreich]

Thanks for the responsive comments. Looks good to me.

[LucieContamin]

I am still a little bit unclear about the process for including custom validation function and the link with the new CSV file (if there is any).

[LucieContamin]

I might need just a little bit more information on the CSV file and the impact of any changes made on it. I am not sure I totally understand the behavior here.

[annakrystalli]

Hey @LucieContamin !

So the csv file holds metadata about standard checks performed by the validate_* family of functions. It is only used to produce the tables with information about checks in the documentation. It does not have any link to custom functions.

The file is not of any concern to users (i.e. they do not need to know about it) as the information is already presented to users in the documentation. It is mainly developers that need to know about it and update it if they add new checks.

Having said that, your question made me realise (and I believe that's actually what @elray1 was referring to when mentioning functions with further arguments/configurations) that I had not documented the optional functions available through the package. I have now:

• added those to check_table.csv
• included tables of optional function details in the section on deploying custom/optional functions
• made clear in the articles that the info on checks refer to standard default checks and added signposting lto the custom functions vignette for more details on optional/custom functions
• added more detail to the contributing section for how to update the check_table.csv

Hopefully this addresses any confusion. If not it would be great if you could let me know what is still confusing and importantly, where you think more information might be reuired.

[LucieContamin]

Thank you for the additional information, it answers all my questions!