joe-heffer-shef / fair4rs-documentation Goto Github PK

This is a course on software documentation for researchers developed by the Research Software Engineering team and IT Services at the University of Sheffield.

Home Page: https://joe-heffer-shef.github.io/FAIR4RS-Documentation/

License: Other

documentation fair4rs reproducible-research research-software-engineering rse software-engineering

fair4rs-documentation's Introduction

Research Software Documentation

This repository contains a course on documenting research software that is part of the training provision for research computing at the University of Sheffield.

Course description

This course will introduce you to the different ways we can provide guidance to future users and maintainers of our code. These coding best practices range from the very simple, such as leaving a few handy notes, to the complex, generating a reference website that includes tutorials and a detailed reference. The right approach for your projects will probably be a blend of these, and depends on the context and your audience.

Course overview

This course introduces the different ways to provide other researchers with useful documentation for your software.

Writing informative README files
- Writing installation instructions
- Writing usage instructions
- Writing contribution guidelines
Improving code readability
- Doc-strings for functions
- Usage examples for functions
- Type hints
Publishing documentation websites
Command line interfaces with usage instructions

There is information about publishing a software package and providing metadata and citation details in Modules 6 and 7 of this course.

Contact us

Please contact Research & Innovation IT or Research Software Engineering at the University of Sheffield.

fair4rs-documentation's People

Contributors

Stargazers

Watchers

Forkers

ns-rse

fair4rs-documentation's Issues

Write CLI episode

I'm not sure if this is in scope for this course

Include Contributor Covenant Code of Conduct

To supplement the contributors episode it might be worth considering including reference to a Code of Conduct as well as Contributing guidelines so that people learn to include not just technical details of how to contribute but to include details of the expected behaviour of contributors.

One resource I've seen used for this in the past are the Contributor Covenant: Code of Conduct.

attempt to concatenate a nil value (field '?')

https://github.com/Joe-Heffer-Shef/FAIR4RS-Documentation/actions/runs/9287879584/job/25557968462#step:7:87

Run reset <- "" == "true"
[1] TRUE
── Validating Fenced Divs ──────────────────────────────────────────────────────
── Validating Internal Links and Images ────────────────────────────────────────
! There were errors in 1/61 links
◌ Some linked internal files do not exist <https://carpentries.github.io/sandpaper/articles/include-child-documents.html#workspace-consideration>

Warning:  [missing file]: [create a new issue](../../issues/new)
Fetch origin/md-outputs
Add worktree for origin/md-outputs in site/built
Build Markdown Sources
Commit Markdown Sources
Fetch origin/gh-pages
Add worktree for origin/gh-pages in site/docs
Build Lesson Website
  ◉ pandoc found
    version : 3.1.11
    path    : '/opt/hostedtoolcache/pandoc/3.1.11/x64'
  ── Initialising site ───────────────────────────────────────────────────────────
  ── Scanning episodes to rebuild ────────────────────────────────────────────────
  ! No yaml header found in the first 10 lines of '/home/runner/work/FAIR4RS-Documentation/FAIR4RS-Documentation/site/built/LICENSE.md'
  ! No yaml header found in the first 10 lines of '/home/runner/work/FAIR4RS-Documentation/FAIR4RS-Documentation/site/built/SECURITY.md'
  Writing `instructor/introduction.html`
  Writing `introduction.html`
  Error running filter /home/runner/work/_temp/Library/sandpaper/rmarkdown/lua/lesson.lua:
  ...er/work/_temp/Library/sandpaper/rmarkdown/lua/lesson.lua:323: attempt to concatenate a nil value (field '?')
  stack traceback:
  	...er/work/_temp/Library/sandpaper/rmarkdown/lua/lesson.lua:461: in function 'tab_block'
  	...er/work/_temp/Library/sandpaper/rmarkdown/lua/lesson.lua:6[36](https://github.com/Joe-Heffer-Shef/FAIR4RS-Documentation/actions/runs/9287879584/job/25557968462#step:7:39): in function 'handle_our_divs'
  Error: 
  ! in callr subprocess.
  Caused by error: 
  ! pandoc document conversion failed with error 83
  ---
  Standard error:
  Error running filter /home/runner/work/_temp/Library/sandpaper/rmarkdown/lua/lesson.lua:
  ...er/work/_temp/Library/sandpaper/rmarkdown/lua/lesson.lua:323: attempt to concatenate a nil value (field '?')
  stack traceback:
  	...er/work/_temp/Library/sandpaper/rmarkdown/lua/lesson.lua:461: in function 'tab_block'
  	...er/work/_temp/Library/sandpaper/rmarkdown/lua/lesson.lua:[63](https://github.com/Joe-Heffer-Shef/FAIR4RS-Documentation/actions/runs/9287879584/job/25557968462#step:7:69)6: in function 'handle_our_divs'
  ---
  Backtrace:
   1. sandpaper:::ci_deploy(reset = reset)
   2. sandpaper:::ci_build_site(path, branch = site_branch, md = md_branch, remote = remote,…
   3. withr::with_dir(path, { …
   4. base::force(code)
   5. sandpaper:::build_site(path = path, quiet = FALSE, preview = FALSE)
   6. sandpaper::build_episode_html(path_md = abs_md[i], path_src = abs_src[i], …
   7. sandpaper:::render_html(path_md, quiet = quiet)
   8. callr::r(function(d, v, ...) { …
   9. callr:::get_result(output = out, options)
  10. callr:::throw(callr_remote_error(remerr, output), parent = fix_msg(remerr[[3]]))
  ---
  Subprocess backtrace:
  1. rmarkdown::pandoc_convert(...)
  2. rmarkdown:::stop2("pandoc document conversion failed with error ", result)
  3. base::stop(..., call. = FALSE)
  4. | base::.handleSimpleError(function (e) …
  5. global h(simpleError(msg, call))
  Running git worktree remove --force \
    /home/runner/work/FAIR4RS-Documentation/FAIR4RS-Documentation/site/docs
  Running git worktree remove --force \
    /home/runner/work/FAIR4RS-Documentation/FAIR4RS-Documentation/site/built
  Execution halted
  Error: Process completed with exit code 1.

Use Roxygen2 for R examples

Sorry to miss the session yesterday @Joe-Heffer-Shef I had school pick-up to do bang in the middle.

I've had a look through the material though and noticed that the example of R documentation in the introduction episode appears to use Python style docstrings which I've never seen before and I don't know how/if they are rendered.

A common convention though is to use roxygen2 for documenting functions (its described in the R Packages (2e) : Function Documentation.

I thought it would be useful use this convention and reference Roxygen2 rather than people learn one way of doing things and then have to re-learn another method.

EDIT : I've found that this is referenced further in the material under Code Readability.

Add questions & keypoints for developer guidance section

Adopt docstring convention

The Scientific Python Documentation Tutorial recommends using numpydoc formatted docstrings in Python as they work well with Sphinx's autodoc and autosummary extensions.

I appreciate not all Python projects will be scientifically aligned but many would be.

This would encourage the use of Type Hints which code bases benefit from having as there are linters which can check type hints are consistent and correct which in turn reduces the amount of errors that can arise when running code (using Type Hints in examples could easily be a separate issue though).

There is also a convention for adding examples sections to docstrings and these can even form the basis of tests for a package via the standard libraries doctest (and of course pytest supports doctest.

Using Type Hints and adding Examples could easily be their own issues so listing below to facilitate creation of these if it is desirable to do so.

Add Type Hints to docstrings for Python examples.
Add Examples to docstrings for Python examples.

Code readability R without syntax highlighting not rendered correctly

The first code box on the R tab of the Code Readability Episode where R code is meant to be shown without syntax highlighting renders with syntax highlighting.

Not sure why this might be as the language is denoted as output in the Markdown file. 🤔

Write questions, objectives and key notes for docstrings episode

attempt to concatenate a nil value (field '?')

https://github.com/Joe-Heffer-Shef/FAIR4RS-Documentation/actions/runs/9304403534/job/25608881297

related to #3

Run reset <- "" == "true"
  reset <- "" == "true"
  sandpaper::package_cache_trigger(TRUE)
  sandpaper:::ci_deploy(reset = reset)
  shell: /usr/bin/Rscript {0}
  env:
    GITHUB_PAT: ***
    RENV_PATHS_ROOT: ~/.local/share/renv/
    R_LIBS_USER: /home/runner/work/_temp/Library
    TZ: UTC
    _R_CHECK_SYSTEM_CLOCK_: FALSE
    NOT_CRAN: true
    RSPM: https://packagemanager.posit.co/cran/__linux__/jammy/latest
    RENV_CONFIG_REPOS_OVERRIDE: https://packagemanager.posit.co/cran/__linux__/jammy/latest
[1] TRUE
── Validating Fenced Divs ──────────────────────────────────────────────────────
── Validating Internal Links and Images ────────────────────────────────────────
! There were errors in 1/69 links
◌ Some linked internal files do not exist <https://carpentries.github.io/sandpaper/articles/include-child-documents.html#workspace-consideration>

Warning:  [missing file]: [create a new issue](../../issues/new)
Fetch origin/md-outputs
Add worktree for origin/md-outputs in site/built
Build Markdown Sources
Commit Markdown Sources
Fetch origin/gh-pages
Add worktree for origin/gh-pages in site/docs
Build Lesson Website
  ◉ pandoc found
    version : 3.1.11
    path    : '/opt/hostedtoolcache/pandoc/3.1.11/x64'
  ── Initialising site ───────────────────────────────────────────────────────────
  ── Scanning episodes to rebuild ────────────────────────────────────────────────
  Writing `instructor/CODE_OF_CONDUCT.html`
  Writing `CODE_OF_CONDUCT.html`
  ! No yaml header found in the first 10 lines of '/home/runner/work/FAIR4RS-Documentation/FAIR4RS-Documentation/site/built/LICENSE.md'
  Writing `instructor/LICENSE.html`
  Writing `LICENSE.html`
  ! No yaml header found in the first 10 lines of '/home/runner/work/FAIR4RS-Documentation/FAIR4RS-Documentation/site/built/SECURITY.md'
  Writing `instructor/SECURITY.html`
  Writing `SECURITY.html`
  Writing `instructor/introduction.html`
  Writing `introduction.html`
  Writing `instructor/readmes.html`
  Writing `readmes.html`
  Writing `instructor/docstrings.html`
  Writing `docstrings.html`
  Writing `instructor/readable.html`
  Writing `readable.html`
  Writing `instructor/pages.html`
  Writing `pages.html`
  Writing `instructor/developers.html`
  Writing `developers.html`
  Error running filter /home/runner/work/_temp/Library/sandpaper/rmarkdown/lua/lesson.lua:
  ...er/work/_temp/Library/sandpaper/rmarkdown/lua/lesson.lua:3[2](https://github.com/Joe-Heffer-Shef/FAIR4RS-Documentation/actions/runs/9304403534/job/25608881297#step:7:2)3: attempt to concatenate a nil value (field '?')
  stack traceback:
  	...er/work/_temp/Library/sandpaper/rmarkdown/lua/lesson.lua:421: in function <...er/work/_temp/Library/sandpaper/rmarkdown/lua/lesson.lua:420>
  	[C]: in ?
  	[C]: in function 'pandoc.walk_block'
  	...er/work/_temp/Library/sandpaper/rmarkdown/lua/lesson.lua:444: in function 'tab_block'
  	...er/work/_temp/Library/sandpaper/rmarkdown/lua/lesson.lua:6[3](https://github.com/Joe-Heffer-Shef/FAIR4RS-Documentation/actions/runs/9304403534/job/25608881297#step:7:3)6: in function 'handle_our_divs'
  stack traceback:
  	...er/work/_temp/Library/sandpaper/rmarkdown/lua/lesson.lua:[4](https://github.com/Joe-Heffer-Shef/FAIR4RS-Documentation/actions/runs/9304403534/job/25608881297#step:7:4)44: in function 'tab_block'
  	...er/work/_temp/Library/sandpaper/rmarkdown/lua/lesson.lua:636: in function 'handle_our_divs'
  Error: 
  ! in callr subprocess.
  Caused by error: 
  ! pandoc document conversion failed with error 83
  ---
  Standard error:
  Error running filter /home/runner/work/_temp/Library/sandpaper/rmarkdown/lua/lesson.lua:
  ...er/work/_temp/Library/sandpaper/rmarkdown/lua/lesson.lua:323: attempt to concatenate a nil value (field '?')
  stack traceback:
  	...er/work/_temp/Library/sandpaper/rmarkdown/lua/lesson.lua:421: in function <...er/work/_temp/Library/sandpaper/rmarkdown/lua/lesson.lua:420>
  	[C]: in ?
  	[C]: in function 'pandoc.walk_block'
  	...er/work/_temp/Library/sandpaper/rmarkdown/lua/lesson.lua:444: in function 'tab_block'
  	...er/work/_temp/Library/sandpaper/rmarkdown/lua/lesson.lua:636: in function 'handle_our_divs'
  stack traceback:
  	...er/work/_temp/Library/sandpaper/rmarkdown/lua/lesson.lua:444: in function 'tab_block'
  	...er/work/_temp/Library/sandpaper/rmarkdown/lua/lesson.lua:636: in function 'handle_our_divs'
  ---
  Backtrace:
   1. sandpaper:::ci_deploy(reset = reset)
   2. sandpaper:::ci_build_site(path, branch = site_branch, md = md_branch, remote = remote,…
   3. withr::with_dir(path, { …
   4. base::force(code)
   [5](https://github.com/Joe-Heffer-Shef/FAIR4RS-Documentation/actions/runs/9304403534/job/25608881297#step:7:5). sandpaper:::build_site(path = path, quiet = FALSE, preview = FALSE)
   [6](https://github.com/Joe-Heffer-Shef/FAIR4RS-Documentation/actions/runs/9304403534/job/25608881297#step:7:6). sandpaper::build_episode_html(path_md = abs_md[i], path_src = abs_src[i], …
   [7](https://github.com/Joe-Heffer-Shef/FAIR4RS-Documentation/actions/runs/9304403534/job/25608881297#step:7:7). sandpaper:::render_html(path_md, quiet = quiet)
   [8](https://github.com/Joe-Heffer-Shef/FAIR4RS-Documentation/actions/runs/9304403534/job/25608881297#step:7:8). callr::r(function(d, v, ...) { …
   [9](https://github.com/Joe-Heffer-Shef/FAIR4RS-Documentation/actions/runs/9304403534/job/25608881297#step:7:9). callr:::get_result(output = out, options)
  [10](https://github.com/Joe-Heffer-Shef/FAIR4RS-Documentation/actions/runs/9304403534/job/25608881297#step:7:10). callr:::throw(callr_remote_error(remerr, output), parent = fix_msg(remerr[[3]]))
  ---
  Subprocess backtrace:
  1. rmarkdown::pandoc_convert(...)
  2. rmarkdown:::stop2("pandoc document conversion failed with error ", result)
  3. base::stop(..., call. = FALSE)
  4. | base::.handleSimpleError(function (e) …
  5. global h(simpleError(msg, call))
  Running git worktree remove --force \
    /home/runner/work/FAIR4RS-Documentation/FAIR4RS-Documentation/site/docs
  Running git worktree remove --force \
    /home/runner/work/FAIR4RS-Documentation/FAIR4RS-Documentation/site/built
  Execution halted
  Error: Process completed with exit code 1.

Clarify language for challenge in Code Readability

The challenge at the end of this episode tests the function add() but its focused on Python since the solution indicates that it won't return an error which is true, in Python the + can be used to concatenate two strings...

In [1]: "cheese" + "cake"
Out[3]: 'cheesecake'

But the material covers R as well and the behaviour is different in this language since the binary operator requires numeric arguments...

> "cheese" + "cake"
Error in "cheese" + "cake" : non-numeric argument to binary operator

Perhaps worth clarifying that the example is being run in Python.

Alternatively could cover answers for both languages indicating no error is raised if run in Python, but that R does raise an error.

Sandpaper Error: fatal problem(s) in xsltParseStylesheetDoc

R output:

> sandpaper::build_lesson()
xslt error: compilation error: file C:/Users/my_username/AppData/Local/Temp/RtmpQbZTVe/file57c5e6b75d3 line 10 element import
xslt error: xsl:import : unable to load C://stfdata09/home/CS/my_username/ManWin/My%20Documents/R/win-library/4.2.1/tinkr/stylesheets/xml2md_gfm.xsl
Error: fatal problem(s) in xsltParseStylesheetDoc: xsl:import : unable to load C://stfdata09/home/CS/my_username/ManWin/My%20Documents/R/win-library/4.2.1/tinkr/stylesheets/xml2md_gfm.xsl
In addition: Warning message:
In doc_xslt_apply(doc$doc, stylesheet$doc, paramstr) :
  failed to load external entity "C://stfdata09/home/CS/my_username/ManWin/My%20Documents/R/win-library/4.2.1/tinkr/stylesheets/xml2md_gfm.xsl" [1549]

sandpaper::serve()

> sandpaper::build_lesson()
xslt error: compilation error: file C:/Users/my_username/AppData/Local/Temp/RtmpuA4vOL/file213f8584d25c5 line 10 element import
xslt error: xsl:import : unable to load C://stfdata09/home/CS/my_username/ManWin/My%20Documents/R/win-library/4.2.1/tinkr/stylesheets/xml2md_gfm.xsl
Error: fatal problem(s) in xsltParseStylesheetDoc: xsl:import : unable to load C://stfdata09/home/CS/my_username/ManWin/My%20Documents/R/win-library/4.2.1/tinkr/stylesheets/xml2md_gfm.xsl
In addition: Warning message:
In doc_xslt_apply(doc$doc, stylesheet$doc, paramstr) :
  failed to load external entity "C://stfdata09/home/CS/my_username/ManWin/My%20Documents/R/win-library/4.2.1/tinkr/stylesheets/xml2md_gfm.xsl" [1549]

session info

> sessionInfo()
R version 4.4.0 (2024-04-24 ucrt)
Platform: x86_64-w64-mingw32/x64
Running under: Windows 10 x64 (build 19045)

Matrix products: default


locale:
[1] LC_COLLATE=English_United Kingdom.utf8  LC_CTYPE=English_United Kingdom.utf8    LC_MONETARY=English_United Kingdom.utf8
[4] LC_NUMERIC=C                            LC_TIME=English_United Kingdom.utf8    

time zone: Europe/London
tzcode source: internal

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base     

loaded via a namespace (and not attached):
 [1] compiler_4.4.0    renv_1.0.3        Rcpp_1.0.11       xml2_1.3.5        tinkr_0.2.0.9000  assertthat_0.2.1 
 [7] callr_3.7.3       credentials_2.0.1 yaml_2.3.7        fastmap_1.1.1     R6_2.5.1          commonmark_1.9.0 
[13] pegboard_0.7.5    knitr_1.43        tibble_3.2.1      rprojroot_2.0.3   openssl_2.1.0     pillar_1.9.0     
[19] rlang_1.1.1       utf8_1.2.3        xfun_0.40         fs_1.6.3          sys_3.4.2         cli_3.6.1        
[25] withr_2.5.0       magrittr_2.0.3    ps_1.7.5          digest_0.6.33     processx_3.8.2    rstudioapi_0.15.0
[31] sandpaper_0.16.4  askpass_1.2.0     gert_1.9.3        lifecycle_1.0.3   vctrs_0.6.3       evaluate_0.21    
[37] glue_1.6.2        whisker_0.4.1     xslt_1.4.5        fansi_1.0.4       rmarkdown_2.24    purrr_1.0.2      
[43] tools_4.4.0       pkgconfig_2.0.3   htmltools_0.5.6

Write doc site episode

No section called ‘questions’

https://github.com/Joe-Heffer-Shef/FAIR4RS-Documentation/actions/runs/9261995501/job/25478224141#step:7:69

Run reset <- "" == "true"
[1] TRUE
✖ A section (div) tag mis-match was detected.
✖ There are not enough open tags (6) for the number of close tags (7).
Missing open section (div) tag in ./episodes/readable.md.
Warning: check for the corresponding open tag
Warning: check for the corresponding open tag
Warning: check for the corresponding open tag
Warning: check for the corresponding open tag
Warning: check for the corresponding open tag
Warning: check for the corresponding open tag
Warning: check for the corresponding open tag
Section (div) tags for readable.md will not be labelledFALSE
── Validating Fenced Divs ──────────────────────────────────────────────────────
✖ A section (div) tag mis-match was detected.
✖ There are not enough open tags (6) for the number of close tags (7).
Error in `purrr::map()`:
ℹ In index: 5.
ℹ With name: readable.md.
Caused by error:
! Missing open section (div) tag in ./episodes/readable.md.
Warning: check for the corresponding open tag
Warning: check for the corresponding open tag
Warning: check for the corresponding open tag
Warning: check for the corresponding open tag
Warning: check for the corresponding open tag
Warning: check for the corresponding open tag
Warning: check for the corresponding open tag
Backtrace:
     ▆
  1. ├─sandpaper:::ci_deploy(reset = reset)
  2. │ └─sandpaper::validate_lesson(path)
  3. │   └─lesson$validate_divs()
  4. │     └─purrr::map(...)
  5. │       └─purrr:::map_("list", .x, .f, ..., .progress = .progress)
  6. │         ├─purrr:::with_indexed_errors(...)
  7. │         │ └─base::withCallingHandlers(...)
  8. │         ├─purrr:::call_with_cleanup(...)
  9. │         └─pegboard (local) .f(.x[[i]], ...)
 10. │           └─x$validate_divs(warn = FALSE)
 11. │             └─pegboard:::validate_divs(self)
 12. │               └─pegboard:::make_div_table(yrn)
 13. │                 └─yrn$label_divs()
 14. │                   └─pegboard:::label_div_tags(self)
 [15](https://github.com/Joe-Heffer-Shef/FAIR4RS-Documentation/actions/runs/9261995501/job/25478224141#step:7:16). │                     └─pegboard:::make_div_pairs(nodes, path = path, yaml = yaml)
 [16](https://github.com/Joe-Heffer-Shef/FAIR4RS-Documentation/actions/runs/9261995501/job/25478224141#step:7:17). │                       └─pegboard:::raise_div_error(res, path, yaml, type = labels$message)
 [17](https://github.com/Joe-Heffer-Shef/FAIR4RS-Documentation/actions/runs/9261995501/job/25478224141#step:7:18). │                         └─base::stop(msg, call. = FALSE)
 18. └─base::.handleSimpleError(...)
 19.   └─purrr (local) h(simpleError(msg, call))
 20.     └─cli::cli_abort(...)
 21.       └─rlang::abort(...)
Warning message:
No section called ‘questions’ 
Execution halted
Error: Process completed with exit code 1.