Generate documentation

[EmiliaJarochowska]

We want to work towards a release, so a simple documentation is needed. I guess only for users, not developers. Perhaps a few typical tasks are expected:

• changing the solver
• setting what is saved as output (how many dts are saved, we ourselves struggled with it a bit]
• saving U at the bottom

Plotting doesn't need to be addresses because we have a separate repo for this, Cross-comparison. This will need to be tidied up a bit separately. This issue is related to #37

[HannoSpreeuw]

• saving U at the bottom

Will be left out, see remark from PR #44 .

[EmiliaJarochowska]

Let's make it pragmatic. What documentation system (for python) are you (most) familiar with, @HannoSpreeuw ?

[HannoSpreeuw]

No recent experience in writing user documentation, only developer documentation, in my case that just meant writings docstrings, sorry.

So I asked the colleague sitting next to me: Which documentation system would you use when writing a tutorial from scratch?

readthedocs, he replied and he especially liked a recent project where a Jupyter notebook was integrated in this documentation system.

Pls let me know how you feel about this.

[HannoSpreeuw]

But there are quite a few options available with e.g. GitBook and Doxygen being viable alternatives.

[EmiliaJarochowska]

That is a nice example, but using a responsive format such as a notebook is applicable if there is an API, in our case user sets all the parameters in one script and then runs one command. For running one command, you don't need a notebook.

This is scientific, not utility software, so the users will engage with the code. So that's ok to only write developer documentation, but the current one is not sufficient. Docstrings can be the biggest part of it, but maybe you could move them a bit closer to PEP 257? As for the rest, I think I could try to list the tasks users (including future us) would typically try to do, but I need a week or so.

I think it is also ok if you don't want to write documentation.

[HannoSpreeuw]

After consulting @jhidding I will go for pdoc.

[EmiliaJarochowska]

Looks as good as anything else; I imagined @jhidding would recommend entangled, but I guess there was a reason not to.

[jhidding]

Entangled doesn't include a document generator (i.e. in CarboKitten this is Documenter.jl). The most used document generator for documenting Python projects is Sphinx, which has many options and extensions but is not so nice to work with. I've seen some projects that used MkDocs, but its API documentation generation is less than stellar. For smaller projects I have worked with pdoc which has a more minimalistic approach. It requires no configuration. Rather, it will read the doc-strings in your module and generate a documentation page from that. Combine that with sourcing an extensive README into that documentation and that's perfect for small projects (that are not written in Entangled 😀).

[HannoSpreeuw]

@jhidding The only thing that worries me now is the rendering.
Suppose I have this docstring snippet:

    Parameters:
    -----------
    solver_parms: dict 
        Parameters about solver settings.
    tracker_parms: dict 
        Parameters about the progress bar and time interval for storage
    pde_parms: dict
        Model parameters, which govern e.g. the physical processes, but
        also the discretization, such as the number of grid cells.

Then it gets rendered like this in the corresponding .html:

Parameters:

solver_parms: dict Parameters about solver settings. tracker_parms: dict Parameters about the progress bar and time interval for storage pde_parms: dict Model parameters, which govern e.g. the physical processes, but also the discretization, such as the number of grid cells.

i.e. it seems to be turned into one line of text.

[HannoSpreeuw]

Allright, you need to write your docstring like this:

    Parameters:
    -----------
    
    - **solver_parms** (*dict*):  
      Parameters about solver settings.
    
    - **tracker_parms** (*dict*):  
      Parameters about the progress bar and time interval for storage.
    
    - **pde_parms** (*dict*):  
      Model parameters, which govern e.g. the physical processes, but 
      also the discretization, such as the number of grid cells.