RSH 4: Workflows and documentation

Video

Collaborative notes taken during the session

What did you learn recently that you are really excited about?

• observable (https://observablehq.com)
  • its like an interactive version of jupyter notebook that has a dependency graph built in. in that sense it is consistently stateful.
  • yes it it collaborative.
• How to build my cpp projects with CMake, make my own libraries and import these dependencies with CMake. I used to hate CMake until a few months ago. No more!
• learned how to couple Rust and Python and to deploy it to PyPI
• GitHub Actions to automate testing/deployments
• [Great tool for working with binary formats](http://kaitai
• thanks guys! enjoyed it again! greetings from germany :)
• Thanks a lot!
• yes, thanks :-) learned a lot!

Discussion

• How do makefiles know which source files have been changed since the recent make?

  • Make decides whether a target needs to be regenerated by comparing file modification times. (https://en.wikipedia.org/wiki/Make_(software))

• You could use .PHONY, there can be a problem if e.g. a file "finalization" is present

• make -j for parallelization

  • This will parallelize a make run automatically

• For workflows, how do you deal with when a pipeline of reproducible expensive steps fails at some point, and maybe something like a Makefile gets confused?

  • If you define the steps in the Makefile, and they have fixed inputs and outputs, it should do the right thing.

• When you're writing documentation for something that has multiple audiences (say, developers of the library, developers integrating the library, and maybe non-technical users further down the line), how do you prioritize what documentation to write?

  • We'll discuss this in the section

• https://meldmerge.org/

• git diff --word-diff=color

• what shell do you use?

  • bash +3
  • tcsh/csh +1
  • zsh +2
  • fish
  • ... ?
  • zsh for interactive, bash for scripting (from chat)
  • is there much difference between shells (from chat)
    • that's tricky, for interactive use not much, for scripting it gets hairy but there are clear differences between C-family shells and sh-family ones (from chat)

• what about "perspectives from different people: developers, users, installers, user support?"

• sphinx-gallery

  • The idea is that with your docstrings, and just a folders in which you dump some examples, you have a pretty complete documentation setup. Get the most bang for your buck. (from chat)
  • All these complicated config files are simply copy/pasted from repositories that went through the trouble of setting all of this stuff up. (from chat)
  • All of this stuff is auto-generated by sphinx. (from chat)
  • Also: examples serve as integration tests (from chat)
  • readthedocs.org

thanks for watching!