docs: add documentation

[rpreen]

@JessUWE this adds quite a few markdown files to the root directory - could they be moved to a docs folder?

Pre-commit needs to be run to clean up.

This warning needs to be fixed:

* checking files in ‘vignettes’ ... WARNING
Warning: Files in the 'vignettes' directory but no files in 'inst/doc':
  ‘example-notebook.Rmd’

I think changing the R-CMD-check.yaml as follows might fix it:

FROM:

      - name: Check R Package
        uses: r-lib/actions/check-r-package@v2
        with:
          upload-snapshots: true

TO:

      - name: Check R Package
        uses: r-lib/actions/check-r-package@v2
        with:
          upload-snapshots: true
          build-vignettes: true

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (431f718) to head (1ae1d12).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main       #30   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            5         5           
  Lines          102       107    +5     
=========================================
+ Hits           102       107    +5     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jim-smith]

@JessUWE the package repository CRAN won't accept having many files in the root directory - they need to be in a directory called "inst"
If you look at the current main branch you can see that I've had to move the images folder and installation.md into inst/ and change some of the links in the main readme.md file.
I've sent those changed versions to CRAN so you should probably pull those changes into this branch to keep things consistent

[JessUWE]

@rpreen Can you check please?

[rpreen]

Looks like there are a lot of files in here that shouldn't be:

• .vscode/ - I don't think editor configs belong in this repo
• vignettes/ contains .swp files that should be removed - add .swp to gitignore
• .Rdata is a binary file - why is it needed?
• docs/ contains a lot of html files - are we expected to edit/maintain these? if they are generated then why aren't they created and pushed to the gh-pages branch?

[rpreen]

The errors and warnings in the R-CMD-check runners need to be addressed.

Non-standard files/directories found at top level:
  ‘docs’ ‘examples.md’ ‘index.md’ ‘installation.md’ ‘pkgdown’
  ‘supports.md’ ‘welcome.md’

Things that CRAN should ignore need to be added to .Rbuildignore - most of the markdown files (examples.md, installation.md, etc.) should really be moved to a subfolder to keep the root clean - the inst/ directory as Jim suggested is one suitable place?

< Potential spelling errors:
<   WORD           FOUND IN
< GPLv           index.md:37
< NK             index.md:29
< PyPI           index.md:38
< Scalable       index.md:43
< TRE            index.md:9
< btn            index.md:7,7,9,9,49,49,49
< crosstab       index.md:39
< finalise       index.md:31
< mitigations    index.md:30
< organisation   index.md:42
< sacro          index.md:7,9
< sm             index.md:7,7,9,9
< statsmodels    index.md:28

These may go away if these files are ignored by CRAN, but otherwise I believe the words need to get added to the ignore file inst/WORDLIST

[JessUWE]

The errors and warnings in the R-CMD-check runners need to be addressed.

Non-standard files/directories found at top level:
  ‘docs’ ‘examples.md’ ‘index.md’ ‘installation.md’ ‘pkgdown’
  ‘supports.md’ ‘welcome.md’

Things that CRAN should ignore need to be added to .Rbuildignore - most of the markdown files (examples.md, installation.md, etc.) should really be moved to a subfolder to keep the root clean - the inst/ directory as Jim suggested is one suitable place?

< Potential spelling errors:
<   WORD           FOUND IN
< GPLv           index.md:37
< NK             index.md:29
< PyPI           index.md:38
< Scalable       index.md:43
< TRE            index.md:9
< btn            index.md:7,7,9,9,49,49,49
< crosstab       index.md:39
< finalise       index.md:31
< mitigations    index.md:30
< organisation   index.md:42
< sacro          index.md:7,9
< sm             index.md:7,7,9,9
< statsmodels    index.md:28

These may go away if these files are ignored by CRAN, but otherwise I believe the words need to get added to the ignore file inst/WORDLIST

@rpreen Yes, I can do that. Hopefully, it will help. I’ve been dealing with several errors in Acro-R since I downloaded it. It’s quite different from a regular Python project. Could you please review the content when you have time? It will be going live soon, and I’d like to finalize everything by tomorrow if possible.

[JessUWE]

@rpreen

[rpreen]

Looking... it seems to be that the test for acro_glm() is not being executed. Revert your changes to test-acro_glm.R?‎

Please:

• move NEWS.md back to the root folder
• remove the .swp file in vignettes/

[JessUWE]

Looking... it seems to be that the test for acro_glm() is not being executed. Revert your changes to test-acro_glm.R?‎

Please:

• move NEWS.md back to the root folder
• remove the .swp file in vignettes/

@rpreen I think everything has passed now. However, I had to replace skip_on_ci() with skip_on_cran() in the file, which was why it wasn’t working before. It should be fine now.

Could I please ask why we’re moving the NEWS.md file back to the root folder? I thought it was supposed to be organized according to CRAN standards.

[rpreen]

Could I please ask why we’re moving the NEWS.md file back to the root folder? I thought it was supposed to be organized according to CRAN standards.

It is standard practice to place LICENSE, README, and CHANGELOG files such as NEWS.md in the root directory of repositories so they are immediately accessible. For example, see the popular dplyr and ggplot2 R packages. It has been in the root directory since the start and gets linked correctly on CRAN

[rpreen]

You've downgraded the setup-python action from v6 to v5 - is this necessary because we will need to watch for the bot attempting to autoupdate it later?

[JessUWE]

Could I please ask why we’re moving the NEWS.md file back to the root folder? I thought it was supposed to be organized according to CRAN standards.

It is standard practice to place LICENSE, README, and CHANGELOG files such as NEWS.md in the root directory of repositories so they are immediately accessible. For example, see the popular dplyr and ggplot2 R packages. It has been in the root directory since the start and gets linked correctly on CRAN

@rpreen I understand the purpose of the license, README, and changelog files. I was just curious about the NEWS.md file maybe because it’s an R project, I expected it to contain more, so it looked a bit unusual to me, which is why I asked. But it has now been moved to the root folder

[rpreen]

Is there a reason for removing the blank lines between functions in test-acro_glm.R because it's harder to read now? All the other test files follow the convention of having a blank line between them.

Since there are no other changes to this file, I suggest reverting the file completely.

[rpreen]

I'm not sure that this is necessary to add on the CI because reticulate is installing the Python package in the virtual environment that is used.

[JessUWE]

@rpreen done! Sorry it took time, had errors and had to do a weird reversal on the code!

[rpreen]

Can you quickly just try removing the pip install acro from the yaml file too? I believe that is doing a system install but reticulate uses its own virtual environment so it's not needed.

[JessUWE]

@rpreen ya done!

[rpreen]

thanks, lgtm