sciware

Sciware

Documentation

How to win users and influence science

https://sciware.flatironinstitute.org/20_Documentation/

https://github.com/flatironinstitute/sciware/tree/main/20_Documentation

Rules of Engagement

Goal:

Activities where participants all actively work to foster an environment which encourages participation across experience levels, coding language fluency, technology choices*, and scientific disciplines.

*though sometimes we try to expand your options

Rules of Engagement

(These will always be a work in progress and will be updated, clarified, or expanded as needed.)

Zoom Specific

Future Sessions

Today’s agenda

Documentation

Documentation: Principles and Definitions

Alex Barnett (CCM)

What is documentation?

Text that helps one use and understand a code or software tool

Who is your audience?

Thinking from your audience’s point of view is crucial

What focus on today?

Won’t talk about today, but related & important

API Documentation: how do I call function X?

##

In high-level languages, API doc accessed from command line, eg

In [1]: ?range
Init signature: range(self, /, *args, **kwargs)
Docstring:     
range(stop) -> range object
range(start, stop[, step]) -> range object

Return an object that produces a sequence of integers from start (inclusive)
to stop (exclusive) by step.  range(i, j) produces i, i+1, i+2, ..., j-1.
start defaults to 0, and stop is omitted!  range(4) produces 0, 1, 2, 3.
These are exactly the valid indices for a list of 4 elements.
When step is given, it specifies the increment (or decrement).

This is called inline documentation.

The range(4) example is good: can read to understand quickly

Many people simply modify examples for their purposes

The bang (!) sentence we find unclear (“stop” is bad argument name?) </div>

API docs for a function

You should aim to break up any repeated task (no matter how small) into a self-contained function with a docstring.

Eg, well-known and useful MATLAB/Octave quadrature function gauss.m (not part of core language):

% GAUSS  nodes x (Legendre points) and weights w
function [x,w] = gauss(N)
  beta = .5./sqrt(1-(2*(1:N-1)).^(-2));
  T = diag(beta,1) + diag(beta,-1);
  [V,D] = eig(T);
  x = diag(D); [x,i] = sort(x);
  w = 2*V(1,i).^2;
end

It’s clear from source code that outputs are x and w, but…

When you ask for (interactive) help, it prints only the docstring, which in MATLAB/Octave is the first contiguous % comment block:

>> help gauss
  GAUSS  nodes x (Legendre points) and weights w

Hmm, why not useful? [Please shout out the many reasons why]

- missing input args, their meaning and types! - missing output args, their order, types, meaning... - no use example! - no mention of quadrature (or teaching that it approximates an integral)

Better docs for gauss.m


>> help gauss
  GAUSS   Nodes (Legendre points) and weights for Gaussian quadrature on [-1,1]

  [x,w] = gauss(N) computes N nodes x and N weights w for Gaussian quadrature
  on the 1D interval [-1,1]. The run-time scales as O(N^3). For example, for f a smooth
  function, [x,w]=gauss(16); dot(f(x),w) approximates the integral of f from -1 to 1.

  Inputs:
        N - number of nodes, a positive integer (recommend 1000 or less)
  Outputs:
        x - N*1 double-precision vector of nodes, which each lie in [-1,1]
        w - 1*N double-precision vector of corresponding weights

  Note: increasing N usually gives more accuracy in the approximating the integral.

Note: precise math description, types/sizes of inputs & outputs, helpful advice to newbies teaching example of quadrature use

Final API advice

The Triangle: API, Test, Documentation

Q: What order should you write these in?
A: Write them all at once!
Good practices are mutually interdependent (Jeff makes this point every Sciware)

Alex recommends: write doc first, then test, only then function body!

READMEs overview

“What is this package and how do I get and run it?”

Narrative docs overview

Tutorials overview

https://emcee.readthedocs.io/en/stable/tutorials/quickstart/ https://github.com/fruzsinaagocs/oscode/blob/master/examples/cosmology.ipynb

Documentation is a form of publication

Your work only makes a difference if people use it.

It will only get widely used if it’s easy to understand and use.

Once you have written a stable code, writing docs takes time, but is well worth it!

It is just as important as publishing papers, conference talks, etc

Job candidates in scientific computing are assessed by their docs & code

Writing API Documentation

Bob Carpenter (CCM)

The doc/test/code triangle

Hints of trouble

Exercise 1

  1. In your favorite language, design a function to sum a sequence of values.
  2. Write documentation for it.
  3. Ask yourself if you can write complete tests for it only looking at the doc.
def mySum(v) ...

template <typename T>
T mySum(const std::vector<T>& v) ...

Answer 1: C++ Documentation with Doxygen

/**
 * Return the sum of the specified inputs.  Starting from
 * a nullary value for the return type, elements of the
 * argument are added in order using `operator+=<T>()`.
 *
 * Example usage and output:
 * ```cpp
 * double x = mySum<double>({});
 * int n = mySum(vector<int>{1, 2, 3});
 * string s = mySum(vector<string>{"hello", " ", "world"});
 * cout << "x = " x << "; n = " << n << "; s = " << s << endl;
 * ```
 * ```
 * x = 0; n = 6; s = hello world
 * ```
 *
 * @tparam T type of arguments
 * @param v vector of arguments
 * @return sum of the elements of v
 */
template <typename T>
T mySum(const std::vector<T>& v) {
  T sum = T();
  for (const T& x : v) sum += x;
  return sum;
}

Answer 1: More questions

Exericse 2

Exericse 2, More questions

New Flatiron Wiki

wiki.flatironinstitute.org

We’d greatly appreciate your feedback.

Survey

https://bit.ly/sciware-docs

Tools to Generate Documentation

How do people write user documentation for scientific software projects?

Lehman Garrison (CCA)

Categories of Documentation

Tools for Narrative Documentation

Narrative Documentation: the README

Formatting the README

Formatting the README

Formatting the README: Markdown

Formatting the README: Markdown Example

File: README.md

# my-cool-project
A one-sentence description of how **cool** my project is

## Installation
1. First step is to run this command:
`pip install my-cool-project`
2. Then try to follow the example below!

## Example
```python
import my_cool_project
my_cool_project.go()
```
If the example doesn't work, check the [Installation](#installation).

Formatting the README: Markdown Example

<img width=60% src=”assets/rendered_readme.md.2.png” class=”plain”>

Formatting the README: reStructuredText

Formatting the README: reStructuredText Example

File: README.rst (renders the same as the Markdown example)

my-cool-project
===============
A one-sentence description of how **cool** my project is

Installation
------------
``pip install my-cool-project``

Example
-------
.. code-block:: python

  import my_cool_project
  my_cool_project.go()

If the example doesn't work, try `Installation <#installation>`_.

Tools for Narrative Documentation: Wiki

Tools for Narrative Documentation: Wiki Example

Documentation Tools: Jekyll + Static Hosting

Documentation Tools: Jekyll + Static Hosting

Documentation Tools: Sphinx + ReadTheDocs

Documentation Tools: Sphinx + ReadTheDocs

Documentation Tools: Sphinx + ReadTheDocs

Documentation Tools: Sphinx + ReadTheDocs

What to put in narrative docs

What to put in narrative docs

Documentation Tools: Sphinx + ReadTheDocs

Sphinx conf.py example (Full Documentation)

  # conf.py

  extensions = [
      'sphinx.ext.autodoc', 'sphinx.ext.autosectionlabel'
  ]

  # General information about the project.
  project = "mycoolproject"
  html_theme = "sphinx_rtd_theme"  # the theme we all know and love
  # but there are many others, like "sphinx_book_theme"

  autosectionlabel_prefix_document = True

Documentation Tools: Sphinx + ReadTheDocs

An example of sphinx.ext.autosectionlabel:

File: index.rst

Introduction
------------

Hello, there! This is some text.

A link back to the section header: :ref:`index:Introduction`.

Documentation Tools: Sphinx + ReadTheDocs

Documentation Tools: Sphinx + ReadTheDocs

Example of API doc generation with sphinx.ext.autodoc:

Documentation Tools: Sphinx + ReadTheDocs

Other Useful Sphinx Extensions

Getting Started